release public preview

public-preview/8.30/specification/cortex-analyst.yaml

@@ -0,0 +1,256 @@
+openapi: 3.0.0
+servers:
+- description: Snowflake API
+  url: https://org-account.snowflakecomputing.com
+info:
+  version: 0.0.1
+  title: Cortex Analyst API
+  description: The Snowflake Cortex Analyst API is a REST API that allows end user
+    to chat with their data leveraging semantic models to generate SQL queries.
+  contact:
+    name: Snowflake, Inc.
+    url: https://snowflake.com
+    email: [email protected]
+paths:
+  /api/v2/cortex/analyst/message:
+    post:
+      operationId: sendMessage
+      tags:
+      - cortex-analyst
+      summary: Send a data question to the Cortex Analyst
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/SendMessageRequest'
+      responses:
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/SendMessageResponse'
+            text/event-stream:
+              schema:
+                type: string
+        '400':
+          $ref: common.yaml#/components/responses/400BadRequest
+        '401':
+          $ref: common.yaml#/components/responses/401Unauthorized
+        '403':
+          $ref: common.yaml#/components/responses/403Forbidden
+        '404':
+          $ref: common.yaml#/components/responses/404NotFound
+        '405':
+          $ref: common.yaml#/components/responses/405MethodNotAllowed
+        '429':
+          $ref: common.yaml#/components/responses/429LimitExceeded
+        '500':
+          $ref: common.yaml#/components/responses/500InternalServerError
+        '503':
+          $ref: common.yaml#/components/responses/503ServiceUnavailable
+        '504':
+          $ref: common.yaml#/components/responses/504GatewayTimeout
+components:
+  schemas:
+    StatusUpdate:
+      type: object
+      properties:
+        status:
+          description: The latest status for processing the request
+          type: string
+        status_message:
+          description: A human readable description on the current request processing
+            status
+          type: string
+      required:
+      - status
+    MessageContentDelta:
+      type: object
+      properties:
+        type:
+          type: string
+        index:
+          type: integer
+          description: The index of the content array this delta object represents
+      discriminator:
+        propertyName: type
+        mapping:
+          text: '#/components/schemas/MessageContentDeltaTextObject'
+          sql: '#/components/schemas/MessageContentDeltaSqlObject'
+          suggestions: '#/components/schemas/MessageContentDeltaSuggestionsObject'
+    MessageContentDeltaTextObject:
+      allOf:
+      - $ref: '#/components/schemas/MessageContentDelta'
+      - title: Text
+        type: object
+        description: The text content that is part of a message.
+        properties:
+          text_delta:
+            type: string
+            description: The delta of the text content, clients should concatenate
+              all deltas for the same index
+            example: To answer the question "What is the profit per store?" we must
+              aggregate sales at the store level
+        required:
+        - text_delta
+    MessageContentDeltaSqlObject:
+      allOf:
+      - $ref: '#/components/schemas/MessageContentDelta'
+      - title: SQL
+        type: object
+        description: The SQL content that is part of a message.
+        properties:
+          statement_delta:
+            type: string
+            description: The delta of the sql statement, clients should concatenate
+              all deltas for the same index
+            example: SELECT store, SUM(profit) FROM sales GROUP BY store
+        required:
+        - statement_delta
+    MessageContentDeltaSuggestionsObject:
+      allOf:
+      - $ref: '#/components/schemas/MessageContentDelta'
+      - title: Suggested Questions
+        type: object
+        description: If SQL cannot be generated, a list of questions the semantic
+          model can generate SQL for.
+        properties:
+          suggestions_delta:
+            $ref: '#/components/schemas/SuggestionDelta'
+        required:
+        - suggestions_delta
+    SuggestionDelta:
+      type: object
+      properties:
+        index:
+          type: integer
+          description: The index of the suggestions array this delta object represents
+        suggestion_delta:
+          type: string
+          description: The delta of a suggestion text, clients should concatenate
+            all deltas for the same index
+    StreamingError:
+      type: object
+      properties:
+        message:
+          type: string
+          description: A description of the error
+        code:
+          type: string
+          description: The Snowflake error code categorizing the error
+        request_id:
+          type: string
+          description: Unique request ID
+    SendMessageResponse:
+      type: object
+      description: The non-streaming response object for the sendMessage
+      properties:
+        message:
+          $ref: '#/components/schemas/MessageObject'
+        request_id:
+          type: string
+          description: Unique request ID
+      required:
+      - message
+    MessageObject:
+      type: object
+      title: The message object
+      description: Represents a message within a chat.
+      properties:
+        role:
+          description: The entity that produced the message. One of `user` or `analyst`.
+          type: string
+          enum:
+          - user
+          - analyst
+        content:
+          description: The content of the message in array of text or SQL.
+          type: array
+          items:
+            $ref: '#/components/schemas/MessageContent'
+      required:
+      - content
+    MessageContent:
+      type: object
+      properties:
+        type:
+          type: string
+          enum:
+          - text
+          - sql
+          - suggestions
+      discriminator:
+        propertyName: type
+        mapping:
+          text: '#/components/schemas/MessageContentTextObject'
+          sql: '#/components/schemas/MessageContentSqlObject'
+          suggestions: '#/components/schemas/MessageContentSuggestionsObject'
+    MessageContentTextObject:
+      allOf:
+      - $ref: '#/components/schemas/MessageContent'
+      - title: Text
+        type: object
+        description: The text content that is part of a message.
+        properties:
+          text:
+            type: string
+            example: To answer the question "What is the profit per store?" we must
+              aggregate sales at the store level
+        required:
+        - text
+    MessageContentSqlObject:
+      allOf:
+      - $ref: '#/components/schemas/MessageContent'
+      - title: SQL
+        type: object
+        description: The SQL content that is part of a message.
+        properties:
+          statement:
+            type: string
+            description: The executable SQL statement
+            example: SELECT store, SUM(profit) FROM sales GROUP BY store
+        required:
+        - statement
+    MessageContentSuggestionsObject:
+      allOf:
+      - $ref: '#/components/schemas/MessageContent'
+      - title: Suggested Questions
+        type: object
+        description: If SQL cannot be generated, a list of questions the semantic
+          model can generate SQL for.
+        properties:
+          suggestions:
+            type: array
+            items:
+              type: string
+              example: What is the lifetime revenue for the top 5 clients?
+        required:
+        - suggestions
+    SendMessageRequest:
+      type: object
+      description: The request object for sendMessage requests
+      properties:
+        semantic_model_file:
+          type: string
+          description: The path to a file stored in a Snowflake Stage holding the
+            semantic model yaml. Must be in the database and schema provided in the
+            url parameters.
+          example: '@my_stage/my_semantic_model.yaml'
+        semantic_model:
+          type: string
+          description: A string containing the entire semantic model yaml
+          example: 'name: my_semantic_model\ntables:\n  - name: orders\n...'
+        stream:
+          type: boolean
+          description: Whether to stream the response or not
+          default: false
+        messages:
+          type: array
+          items:
+            $ref: '#/components/schemas/MessageObject'
+      required:
+      - messages
+tags:
+- name: cortex-analyst