Azure Synapse Analytics Databases API

openapi: 3.2.0
info:
  title: ArtifactsClient Databases API
  description: SyMS API Service Client.
  version: '2021-04-01'
tags:
- name: Databases
paths:
  /databases/ExecuteChange:
    post:
      summary: Batch execution of DDL Payload
      operationId: ExecuteChange
      parameters:
      - $ref: '#/components/parameters/ApiVersionParameter'
      responses:
        '200':
          description: Successfully completed the management operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SyMSAPIDDLResponses'
        default:
          description: SyMS error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloudError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DDLBatch'
        description: DDLBatch payload containing artifact drafts to be created or deleted or modified
        required: true
      tags:
      - Databases
  /databases/ExecuteChangeWithValidation:
    post:
      summary: Batch execution of DDL Payload
      operationId: ExecuteChangeWithValidation
      x-ms-long-running-operation: true
      parameters:
      - in: query
        name: validationType
        description: Validation Type - Currently only IDWValidation is supported
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/ApiVersionParameter'
      responses:
        '202':
          description: Returns location header with operation Id
        default:
          description: SyMS error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloudError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DDLBatch'
        description: DDLBatch containing artifacts to be Created or Deleted or Modified.
        required: true
      tags:
      - Databases
  /databases:
    get:
      summary: Get all databases in a workspace
      operationId: ListDatabases
      parameters:
      - $ref: '#/components/parameters/ApiVersionParameter'
      - name: continuationToken
        in: query
        description: Continuation token to get next page.
        required: false
        schema:
          type: string
      - name: maxPageSize
        in: query
        description: Max page size.
        required: false
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Successfully returned details of all the databases in a workspace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryArtifactsResponse'
        default:
          description: SyMS error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloudError'
      tags:
      - Databases
  /databases/{databaseName}/{artifactType}s:
    get:
      summary: List all Artifacts of a type in a database
      operationId: ListArtifacts
      parameters:
      - name: databaseName
        in: path
        description: Database name.
        required: true
        schema:
          type: string
      - name: artifactType
        in: path
        description: Artifact type.
        required: true
        x-ms-enum:
          name: SASEntityType
          modelAsString: false
        schema:
          type: string
          enum:
          - DATABASE
          - TABLE
          - SCHEMA
          - VIEW
          - FUNCTION
          - PARTITIONINFO
          - RELATIONSHIP
      - $ref: '#/components/parameters/ApiVersionParameter'
      - name: continuationToken
        in: query
        description: Continuation token to get next page.
        required: false
        schema:
          type: string
      - name: maxPageSize
        in: query
        description: Max page size.
        required: false
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Successfully returned details of all artifact types in a database.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryArtifactsResponse'
        default:
          description: SyMS error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloudError'
      tags:
      - Databases
  /databases/{databaseName}/schemas/{schemaName}/{artifactType}s:
    get:
      summary: List all artifacts in schema by type
      operationId: ListArtifactsInSchemaByType
      description: List all Artifacts in schema by type
      parameters:
      - name: databaseName
        in: path
        description: Database name.
        required: true
        schema:
          type: string
      - name: schemaName
        in: path
        description: Schema name.
        required: true
        schema:
          type: string
      - name: artifactType
        in: path
        description: Artifact type.
        required: true
        x-ms-enum:
          name: SASEntityType
          modelAsString: false
        schema:
          type: string
          enum:
          - DATABASE
          - TABLE
          - SCHEMA
          - VIEW
          - FUNCTION
          - PARTITIONINFO
          - RELATIONSHIP
      - $ref: '#/components/parameters/ApiVersionParameter'
      - name: continuationToken
        in: query
        description: Continuation token to get next page.
        required: false
        schema:
          type: string
      - name: maxPageSize
        in: query
        description: Max page size.
        required: false
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Successfully returned details of all artifacts by type from schema.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryArtifactsResponse'
        default:
          description: SyMS error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloudError'
      tags:
      - Databases
  /databases/{databaseName}/tables/{tableName}/partitionInfos:
    get:
      summary: List all partition information for a table
      operationId: ListPartitionInfosForTable
      parameters:
      - name: databaseName
        in: path
        description: Database name.
        required: true
        schema:
          type: string
      - name: tableName
        in: path
        description: Table name.
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/ApiVersionParameter'
      - name: continuationToken
        in: query
        description: Continuation token to get next page.
        required: false
        schema:
          type: string
      - name: maxPageSize
        in: query
        description: Max page size.
        required: false
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Successfully returned partition infos in a table.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryArtifactsResponse'
        default:
          description: SyMS error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloudError'
      tags:
      - Databases
  /databases/{databaseName}/views/{viewName}/partitionInfos:
    get:
      summary: List all partition information for a view
      operationId: ListPartitionInfosForView
      parameters:
      - name: databaseName
        in: path
        description: Database name.
        required: true
        schema:
          type: string
      - name: viewName
        in: path
        description: View name.
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/ApiVersionParameter'
      - name: continuationToken
        in: query
        description: Continuation token to get next page.
        required: false
        schema:
          type: string
      - name: maxPageSize
        in: query
        description: Max page size.
        required: false
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Successfully returned partition infos for a view.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryArtifactsResponse'
        default:
          description: SyMS error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloudError'
      tags:
      - Databases
  /databases/{databaseName}/schemas/{schemaName}/tables/{tableName}/partitionInfos:
    get:
      summary: List all partition information for table in schema
      operationId: ListPartitionInfosForSchemaAndTable
      description: List all partition information for a table in schema
      parameters:
      - name: databaseName
        in: path
        description: Database name.
        required: true
        schema:
          type: string
      - name: schemaName
        in: path
        description: Schema name.
        required: true
        schema:
          type: string
      - name: tableName
        in: path
        description: Table name.
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/ApiVersionParameter'
      - name: continuationToken
        in: query
        description: Continuation token to get next page.
        required: false
        schema:
          type: string
      - name: maxPageSize
        in: query
        description: Max page size.
        required: false
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Successfully returned partition infos for a table in schema
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryArtifactsResponse'
        default:
          description: SyMS error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloudError'
      tags:
      - Databases
  /databases/{databaseName}/schemas/{schemaName}/views/{viewName}/partitionInfos:
    get:
      summary: List all partition information for a view in schema
      operationId: ListPartitionInfosForSchemaAndView
      parameters:
      - name: databaseName
        in: path
        description: Database name.
        required: true
        schema:
          type: string
      - name: schemaName
        in: path
        description: Schema name.
        required: true
        schema:
          type: string
      - name: viewName
        in: path
        description: View name.
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/ApiVersionParameter'
      - name: continuationToken
        in: query
        description: Continuation token to get next page.
        required: false
        schema:
          type: string
      - name: maxPageSize
        in: query
        description: Max page size.
        required: false
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Successfully returned details of partition infos for the view
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryArtifactsResponse'
        default:
          description: SyMS error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloudError'
      tags:
      - Databases
  /databases/{databaseName}:
    get:
      summary: Get details about a database
      operationId: GetDatabase
      parameters:
      - name: databaseName
        in: path
        description: Database name.
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/ApiVersionParameter'
      responses:
        '200':
          description: Successfully returned database information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatabaseEntity'
        default:
          description: SyMS error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloudError'
      tags:
      - Databases
    put:
      summary: Put a database
      operationId: PutDatabase
      parameters:
      - name: databaseName
        in: path
        description: Database name.
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/ApiVersionParameter'
      responses:
        '200':
          description: Successfully completed creating/updating database
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SyMSAPIDDLResponse'
        default:
          description: SyMS error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloudError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DatabaseEntity'
        description: Database entity payload to create or update a Database
        required: true
      tags:
      - Databases
    delete:
      summary: Delete a database
      operationId: DeleteDatabase
      parameters:
      - name: databaseName
        in: path
        description: Database name.
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/ApiVersionParameter'
      responses:
        '200':
          description: Successfully deleted the database.
        default:
          description: SyMS error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloudError'
      tags:
      - Databases
  /databases/{databaseName}/{artifactType}s/{artifactName}:
    get:
      summary: Get an artifact from database
      operationId: GetArtifactFromDB
      parameters:
      - name: databaseName
        in: path
        description: Database name.
        required: true
        schema:
          type: string
      - name: artifactType
        in: path
        description: Artifact type.
        required: true
        x-ms-enum:
          name: SASEntityType
          modelAsString: false
        schema:
          type: string
          enum:
          - DATABASE
          - TABLE
          - SCHEMA
          - VIEW
          - FUNCTION
          - PARTITIONINFO
          - RELATIONSHIP
      - name: artifactName
        in: path
        description: Artifact name.
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/ApiVersionParameter'
      responses:
        '200':
          description: Successfully returned artifact details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MDEntity'
        default:
          description: SyMS error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloudError'
      tags:
      - Databases
    put:
      summary: Put an artifact in a Database
      operationId: PutArtifactInDB
      parameters:
      - name: databaseName
        in: path
        description: Database name.
        required: true
        schema:
          type: string
      - name: artifactType
        in: path
        description: Artifact type.
        required: true
        x-ms-enum:
          name: SASEntityType
          modelAsString: false
        schema:
          type: string
          enum:
          - DATABASE
          - TABLE
          - SCHEMA
          - VIEW
          - FUNCTION
          - PARTITIONINFO
          - RELATIONSHIP
      - name: artifactName
        in: path
        description: Artifact name.
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/ApiVersionParameter'
      - name: continuationToken
        in: query
        description: Continuation token to get next page.
        required: false
        schema:
          type: string
      - name: maxPageSize
        in: query
        description: Max page size.
        required: false
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Successfully created/updated artifact in Database
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SyMSAPIDDLResponse'
        default:
          description: SyMS error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloudError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MDEntity'
        description: Payload containing artifact entity to be created/modified
        required: true
      tags:
      - Databases
    delete:
      summary: Delete an artifact in a Database
      operationId: DeleteArtifactForDB
      parameters:
      - name: databaseName
        in: path
        description: Database name.
        required: true
        schema:
          type: string
      - name: artifactType
        in: path
        description: Artifact type
        required: true
        x-ms-enum:
          name: SASEntityType
          modelAsString: false
        schema:
          type: string
          enum:
          - DATABASE
          - TABLE
          - SCHEMA
          - VIEW
          - FUNCTION
          - PARTITIONINFO
          - RELATIONSHIP
      - name: artifactName
        in: path
        description: Artifact name.
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/ApiVersionParameter'
      responses:
        '200':
          description: Successfully deleted artifact from database
        default:
          description: SyMS error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloudError'
      tags:
      - Databases
  /databases/{databaseName}/schemas/{schemaName}/{artifactType}s/{artifactName}:
    get:
      summary: Get an artifact from schema
      operationId: GetArtifactFromSchema
      parameters:
      - name: databaseName
        in: path
        description: Database name.
        required: true
        schema:
          type: string
      - name: schemaName
        in: path
        description: Schema name.
        required: true
        schema:
          type: string
      - name: artifactType
        in: path
        description: Artifact type.
        required: true
        x-ms-enum:
          name: SASEntityType
          modelAsString: false
        schema:
          type: string
          enum:
          - DATABASE
          - TABLE
          - SCHEMA
          - VIEW
          - FUNCTION
          - PARTITIONINFO
          - RELATIONSHIP
      - name: artifactName
        in: path
        description: Artifact name.
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/ApiVersionParameter'
      responses:
        '200':
          description: Successfully returned schema artifact info
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MDEntity'
        default:
          description: SyMS error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloudError'
      tags:
      - Databases
    put:
      summary: Create or Update an artifact in a schema
      operationId: PutArtifactInSchema
      parameters:
      - name: databaseName
        in: path
        description: Database name.
        required: true
        schema:
          type: string
      - name: schemaName
        in: path
        description: Schema name.
        required: true
        schema:
          type: string
      - name: artifactType
        in: path
        description: Artifact type.
        required: true
        x-ms-enum:
          name: SASEntityType
          modelAsString: false
        schema:
          type: string
          enum:
          - DATABASE
          - TABLE
          - SCHEMA
          - VIEW
          - FUNCTION
          - PARTITIONINFO
          - RELATIONSHIP
      - name: artifactName
        in: path
        description: Artifact name.
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/ApiVersionParameter'
      responses:
        '200':
          description: Successfully completed creating/updating artifact in schema
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SyMSAPIDDLResponse'
        default:
          description: SyMS error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloudError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MDEntity'
        description: Payload containing artifact object to be create/updated
        required: true
      tags:
      - Databases
    delete:
      summary: Delete an artifact from Schema
      operationId: DeleteArtifactFromSchema
      parameters:
      - name: databaseName
        in: path
        description: Database name.
        required: true
        schema:
          type: string
      - name: schemaName
        in: path
        description: Schema name.
        required: true
        schema:
          type: string
      - name: artifactType
        in: path
        description: Artifact type.
        required: true
        x-ms-enum:
          name: SASEntityType
          modelAsString: false
        schema:
          type: string
          enum:
          - DATABASE
          - TABLE
          - SCHEMA
          - VIEW
          - FUNCTION
          - PARTITIONINFO
          - RELATIONSHIP
      - name: artifactName
        in: path
        description: Artifact name.
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/ApiVersionParameter'
      responses:
        '200':
          description: Successfully deleted artifact from Schema
        default:
          description: SyMS error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloudError'
      tags:
      - Databases
  /databases/operations/{operationId}:
    get:
      summary: Get the status of validation by operation Id
      operationId: GetSyMSOperationStatus
      parameters:
      - name: operationId
        in: path
        description: Operation Id.
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/ApiVersionParameter'
      responses:
        '200':
          description: Successfully returned the status of given operation Id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryArtifactsResponse'
        default:
          description: SyMS error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloudError'
      tags:
      - Databases
components:
  schemas:
    SyMSAPIDDLResponses:
      description: Defines the publish response.
      type: object
      properties:
        syMsApiDdlResponse:
          description: List of DDL response.
          type: array
          items:
            $ref: '#/components/schemas/SyMSAPIDDLResponse'
      required:
      - syMsApiDdlResponse
    DatabaseProperties:
      description: Database properties.
      type: object
      allOf:
      - $ref: '#/components/schemas/MDEntityProperties'
      properties:
        source:
          $ref: '#/components/schemas/DataSource'
        description:
          description: Description of the database.
          type: string
      required:
      - source
    DDLPayload:
      description: DDL payload
      type: object
      properties:
        actionType:
          $ref: '#/components/schemas/DDLType'
        oldEntity:
          $ref: '#/components/schemas/MDEntity'
        newEntity:
          $ref: '#/components/schemas/MDEntity'
      required:
      - actionType
    DataSource:
      description: Data source properties.
      type: object
      properties:
        provider:
          description: Data source provider information.
          type: string
        location:
          description: Data source location.
          type: string
        properties:
          description: Property bag.
          type: object
          additionalProperties:
            type: object
      required:
      - location
    PublishStatus:
      description: Publish status.
      type: string
      enum:
      - PUBLISHED
      x-ms-enum:
        name: PublishStatus
        modelAsString: false
    DatabaseEntity:
      description: Database entity.
      type: object
      allOf:
      - $ref: '#/components/schemas/MDEntity'
      properties:
        properties:
          $ref: '#/components/schemas/DatabaseProperties'
      required:
      - properties
    SyMSAPIDDLResponse:
      description: Defines the response for create/publish operation on DDL payload.
      type: object
      properties:
        ddlType:
          $ref: '#/components/schemas/DDLType'
        entityName:
          description: Entity name.
          type: string
        entityType:
          $ref: '#/components/schemas/ArtifactType'
        publishStatus:
          $ref: '#/components/schemas/PublishStatus'
        originObjectId:
          description: Object id maintained by Origin Catalog.
          type: string
        objectId:
          description: Object id maintained by SyMS.
          type: string
        objectVersion:
          description: Object version maintained by SyMS.
          type: integer
          format: int64
      required:
      - ddlType
      - entityName
      - entityType
      - publishStatus
      - originObjectId
      - objectId
      - objectVersion
    DDLBatch:
      description: DDL batch.
      type: object
      properties:
        ddls:
          type: array
          items:
            $ref: '#/components/schemas/DDLPayload'
      required:
      - ddls
    ArtifactType:
      description: Artifact type.
      type: string
      enum:
      - DATABASE
      - TABLE
      - SCHEMA
      - VIEW
      - FUNCTION
      - PARTITIONINFO
      - RELATIONSHIP
      x-ms-enum:
        name: SASEntityType
        modelAsString: false
    CloudError:
      x-ms-external: true
      description: The object that defines the structure of an Azure Synapse error response.
      type: object
      properties:
        error:
          x-ms-client-flatten: true
          description: Error data
          $ref: '#/components/schemas/CloudErrorBody'
      required:
      - error
    MDEntityProperties:
      description: Defines the artifact entity.
      type: object
      properties:
        originObjectId:
          description: Entity object id maintained by the caller.
          type: string
        objectId:
          description: Entity object id maintained by SyMS.
          type: string
          readOnly: true
        objectVersion:
          description: Entity object version maintained by SyMS.
          type: integer
          format: int64
          readOnly: true
        publishStatus:
          $ref: '#/components/schemas/PublishStatus'
        properties:
          description: Property bag
          type: object
          additionalProperties:
            type: object
    DDLType:
      description: DDL type.
      type: string
      enum:
      - CREATE
      - ALTER
      - DROP
      x-ms-enum:
        name: DDLType
        modelAsString: false
    MDEntity:
      description: MD Entity
      type: object
      properties:
        name:
          description: Entity Name.
          type: string
        type:
          $ref: '#/components/schemas/ArtifactType'
        id:
          description: Entity Resource Id.
          type: string
          readOnly: true
        properties:
          type: object
      required:
      - name
      - type
    QueryArtifactsResponse:
      description: Query artifacts response.
      type: object
      properties:
        items:
          type: array
          items:
            description: MDEntity (Database/Table/Schema/View/PartitionInfo/PermissionAssignment
            type: object
        continuationToken:
          description: Continuation token to get next page.
          type: string
  parameters:
    ApiVersionParameter:
      name: api-version
      in: query
      required: true
      x-ms-parameter-location: client
      description: The Synapse client API Version.
      schema:
        type: string
x-ms-parameterized-host:
  hostTemplate: '{endpoint}'
  useSchemePrefix: false
  parameters:
  - $ref: '#/components/parameters/Endpoint'