versioned_docs/version-0.8.0-incubating/open-api/tags.yaml [18:396]:
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
---

paths:

  /metalakes/{metalake}/tags:
    parameters:
      - $ref: "./openapi.yaml#/components/parameters/metalake"
    get:
      tags:
        - tag
      summary: List tags (names)
      operationId: listTags
      parameters:
        - $ref: "#/components/parameters/details"
      responses:
        "200":
          description: Returns the list of tag objects if {details} is true, otherwise returns the list of tag name
          content:
            application/vnd.gravitino.v1+json:
              schema:
                oneOf:
                  - $ref: "./openapi.yaml#/components/schemas/NameListResponse"
                  - $ref: "#/components/responses/TagListResponse"
              examples:
                NameListResponse:
                  $ref: "#/components/examples/NameListResponse"
                TagListResponse:
                  $ref: "#/components/examples/TagListResponse"
        "400":
          $ref: "./openapi.yaml#/components/responses/BadRequestErrorResponse"
        "404":
          description: Not Found - The specified metalake does not exist
          content:
            application/vnd.gravitino.v1+json:
              schema:
                $ref: "./openapi.yaml#/components/schemas/ErrorModel"
              examples:
                NoSuchMetalakeException:
                  $ref: "./metalakes.yaml#/components/examples/NoSuchMetalakeException"
        "5xx":
          $ref: "./openapi.yaml#/components/responses/ServerErrorResponse"

    post:
      tags:
        - tag
      summary: Create tag
      operationId: createTag
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/requests/TagCreateRequest"
            examples:
              TagCreate:
                $ref: "#/components/examples/TagCreate"

      responses:
        "200":
          description: Returns the created tag object
          content:
            application/vnd.gravitino.v1+json:
              schema:
                $ref: "#/components/responses/TagResponse"
              examples:
                TagResponse:
                  $ref: "#/components/examples/TagResponse"
        "409":
          description: Conflict - The target tag already exists in the specified metalake
          content:
            application/vnd.gravitino.v1+json:
              schema:
                $ref: "./openapi.yaml#/components/schemas/ErrorModel"
              examples:
                TagAlreadyExistsException:
                  $ref: "#/components/examples/TagAlreadyExistsException"
        "5xx":
          $ref: "./openapi.yaml#/components/responses/ServerErrorResponse"


  /metalakes/{metalake}/tags/{tag}:
    parameters:
      - $ref: "./openapi.yaml#/components/parameters/metalake"
      - $ref: "./openapi.yaml#/components/parameters/tag"

    get:
      tags:
        - tag
      summary: Get tag
      operationId: getTag
      description: Returns the specified tag information in the specified metalake
      responses:
        "200":
          description: Returns the tag object
          content:
            application/vnd.gravitino.v1+json:
              schema:
                $ref: "#/components/responses/TagResponse"
                examples:
                  TagResponse:
                    $ref: "#/components/examples/TagResponse"
        "404":
          description: Not Found - The specified tag does not exist in the specified metalake
          content:
            application/vnd.gravitino.v1+json:
              schema:
                $ref: "./openapi.yaml#/components/schemas/ErrorModel"
              examples:
                NoSuchMetalakeException:
                  $ref: "./metalakes.yaml#/components/examples/NoSuchMetalakeException"
                NoSuchTagException:
                  $ref: "#/components/examples/NoSuchTagException"
        "5xx":
          $ref: "./openapi.yaml#/components/responses/ServerErrorResponse"

    put:
      tags:
        - tag
      summary: Update tag
      operationId: alterTag
      description: Alters the specified tag information in the specified metalake
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/requests/TagUpdatesRequest"
      responses:
        "200":
            description: Returns the updated tag object
            content:
              application/vnd.gravitino.v1+json:
                schema:
                  $ref: "#/components/responses/TagResponse"
                examples:
                  TagResponse:
                    $ref: "#/components/examples/TagResponse"
        "404":
          description: Not Found - The specified tag does not exist in the specified metalake
          content:
            application/vnd.gravitino.v1+json:
              schema:
                $ref: "./openapi.yaml#/components/schemas/ErrorModel"
              examples:
                NoSuchMetalakeException:
                  $ref: "./metalakes.yaml#/components/examples/NoSuchMetalakeException"
                NoSuchTagException:
                  $ref: "#/components/examples/NoSuchTagException"
        "5xx":
          $ref: "./openapi.yaml#/components/responses/ServerErrorResponse"

    delete:
      tags:
        - tag
      summary: Delete tag
      operationId: deleteTag
      responses:
        "200":
          $ref: "./openapi.yaml#/components/responses/DropResponse"
        "400":
          $ref: "./openapi.yaml#/components/responses/BadRequestErrorResponse"
        "5xx":
          $ref: "./openapi.yaml#/components/responses/ServerErrorResponse"


  /metalakes/{metalake}/objects/{metadataObjectType}/{metadataObjectFullName}/tags:
    parameters:
      - $ref: "./openapi.yaml#/components/parameters/metalake"
      - $ref: "./openapi.yaml#/components/parameters/metadataObjectType"
      - $ref: "./openapi.yaml#/components/parameters/metadataObjectFullName"
    get:
      tags:
        - tag
      summary: List tags (names) for metadata object
      operationId: listObjectTags
      parameters:
        - $ref: "#/components/parameters/details"
      responses:
        "200":
          description: Returns the list of tag objects associated with specified metadata object if {details} is true, otherwise returns the list of tag name
          content:
            application/vnd.gravitino.v1+json:
              schema:
                oneOf:
                  - $ref: "./openapi.yaml#/components/schemas/NameListResponse"
                  - $ref: "#/components/responses/TagListResponse"
              examples:
                NameListResponse:
                  $ref: "#/components/examples/NameListResponse"
                TagListResponse:
                  $ref: "#/components/examples/TagListResponse"
        "400":
          $ref: "./openapi.yaml#/components/responses/BadRequestErrorResponse"
        "404":
          description: Not Found - The specified metalake does not exist
          content:
            application/vnd.gravitino.v1+json:
              schema:
                $ref: "./openapi.yaml#/components/schemas/ErrorModel"
              examples:
                NoSuchMetalakeException:
                  $ref: "./metalakes.yaml#/components/examples/NoSuchMetalakeException"
        "5xx":
          $ref: "./openapi.yaml#/components/responses/ServerErrorResponse"

    post:
      tags:
        - tag
      summary: Associate tags with metadata object
      description: Associate and disassociate tags with metadata object, please be aware that supported metadata objects are CATALOG, SCHEMA, TABLE, FILESET, TOPIC, COLUMN
      operationId: associateTags
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/requests/TagsAssociateRequest"
            examples:
              TagAssociate:
                $ref: "#/components/examples/TagAssociate"
      responses:
        "200":
          description: Returns the list of tag names associated with the specified metadata object
          content:
            application/vnd.gravitino.v1+json:
              schema:
                $ref: "./openapi.yaml#/components/schemas/NameListResponse"
              examples:
                NameListResponse:
                  $ref: "#/components/examples/NameListResponse"
        "404":
          description: Not Found - The specified metalake does not exist
          content:
            application/vnd.gravitino.v1+json:
              schema:
                $ref: "./openapi.yaml#/components/schemas/ErrorModel"
              examples:
                NoSuchMetalakeException:
                  $ref: "./metalakes.yaml#/components/examples/NoSuchMetalakeException"
        "409":
          description: Conflict - The target tag already associated with the specified metadata object
          content:
            application/vnd.gravitino.v1+json:
              schema:
                $ref: "./openapi.yaml#/components/schemas/ErrorModel"
              examples:
                TagAlreadyAssociatedException:
                  $ref: "#/components/examples/TagAlreadyAssociatedException"
        "5xx":
          $ref: "./openapi.yaml#/components/responses/ServerErrorResponse"


  /metalakes/{metalake}/objects/{metadataObjectType}/{metadataObjectFullName}/tags/{tag}:
    parameters:
      - $ref: "./openapi.yaml#/components/parameters/metalake"
      - $ref: "./openapi.yaml#/components/parameters/metadataObjectType"
      - $ref: "./openapi.yaml#/components/parameters/metadataObjectFullName"
      - $ref: "./openapi.yaml#/components/parameters/tag"
    get:
      tags:
        - tag
      summary: Get tag for metadata object
      operationId: getObjectTag
      parameters:
        - $ref: "#/components/parameters/details"
      responses:
        "200":
          description: Returns the list of tag objects associated with specified metadata object if {details} is true, otherwise returns the list of tag name
          content:
            application/vnd.gravitino.v1+json:
              schema:
                $ref: "#/components/responses/TagResponse"
              examples:
                TagResponse:
                  $ref: "#/components/examples/TagResponse"
        "400":
          $ref: "./openapi.yaml#/components/responses/BadRequestErrorResponse"
        "404":
          description: Not Found - The specified metalake does not exist or the specified tag is not associated with the specified metadata object
          content:
            application/vnd.gravitino.v1+json:
              schema:
                $ref: "./openapi.yaml#/components/schemas/ErrorModel"
              examples:
                NoSuchTagException:
                  $ref: "#/components/examples/NoSuchTagException"
                NoSuchMetalakeException:
                  $ref: "./metalakes.yaml#/components/examples/NoSuchMetalakeException"
        "5xx":
          $ref: "./openapi.yaml#/components/responses/ServerErrorResponse"


  /metalakes/{metalake}/tags/{tag}/objects:
    parameters:
      - $ref: "./openapi.yaml#/components/parameters/metalake"
      - $ref: "./openapi.yaml#/components/parameters/tag"
    get:
      tags:
        - tag
      summary: list metadata objects for tag
      operationId: listTagObjects
      responses:
        "200":
          description: Returns the list of metadata objects associated with specified tag
          content:
            application/vnd.gravitino.v1+json:
              schema:
                $ref: "#/components/responses/MetadataObjectListResponse"
              examples:
                TagResponse:
                  $ref: "#/components/examples/MetadataObjectListResponse"
        "400":
          $ref: "./openapi.yaml#/components/responses/BadRequestErrorResponse"
        "404":
          description: Not Found - The specified tag does not exist
          content:
            application/vnd.gravitino.v1+json:
              schema:
                $ref: "./openapi.yaml#/components/schemas/ErrorModel"
              examples:
                NoSuchTagException:
                  $ref: "#/components/examples/NoSuchTagException"
        "5xx":
          $ref: "./openapi.yaml#/components/responses/ServerErrorResponse"


components:
  parameters:
    details:
      name: details
      in: query
      description: Include detailed information about the tag
      required: false
      schema:
        type: boolean
        default: false

  schemas:

    Tag:
      type: object
      description: A tag
      required:
        - name
        - audit
      properties:
        name:
          type: string
          description: The name of the tag
        comment:
          type: string
          description: A comment about the tag
          nullable: true
        audit:
          $ref: "./openapi.yaml#/components/schemas/Audit"
        properties:
          type: object
          description: Configured string to string map of properties for the tag
          default: { }
          additionalProperties:
            type: string
        inherited:
          type: boolean
          description: Whether the tag is inherited from the parent metadata object
          nullable: true

    MetadataObject:
      type: object
      description: A metadata object
      properties:
        fullName:
          type: string
          description: The name of the metadata object, separated by dots
        type:
          type: string
          description: The type of the metadata object
          enum:
            - "CATALOG"
            - "SCHEMA"
            - "TABLE"
            - "FILESET"
            - "TOPIC"
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -



versioned_docs/version-0.9.0-incubating/open-api/tags.yaml [18:396]:
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
---

paths:

  /metalakes/{metalake}/tags:
    parameters:
      - $ref: "./openapi.yaml#/components/parameters/metalake"
    get:
      tags:
        - tag
      summary: List tags (names)
      operationId: listTags
      parameters:
        - $ref: "#/components/parameters/details"
      responses:
        "200":
          description: Returns the list of tag objects if {details} is true, otherwise returns the list of tag name
          content:
            application/vnd.gravitino.v1+json:
              schema:
                oneOf:
                  - $ref: "./openapi.yaml#/components/schemas/NameListResponse"
                  - $ref: "#/components/responses/TagListResponse"
              examples:
                NameListResponse:
                  $ref: "#/components/examples/NameListResponse"
                TagListResponse:
                  $ref: "#/components/examples/TagListResponse"
        "400":
          $ref: "./openapi.yaml#/components/responses/BadRequestErrorResponse"
        "404":
          description: Not Found - The specified metalake does not exist
          content:
            application/vnd.gravitino.v1+json:
              schema:
                $ref: "./openapi.yaml#/components/schemas/ErrorModel"
              examples:
                NoSuchMetalakeException:
                  $ref: "./metalakes.yaml#/components/examples/NoSuchMetalakeException"
        "5xx":
          $ref: "./openapi.yaml#/components/responses/ServerErrorResponse"

    post:
      tags:
        - tag
      summary: Create tag
      operationId: createTag
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/requests/TagCreateRequest"
            examples:
              TagCreate:
                $ref: "#/components/examples/TagCreate"

      responses:
        "200":
          description: Returns the created tag object
          content:
            application/vnd.gravitino.v1+json:
              schema:
                $ref: "#/components/responses/TagResponse"
              examples:
                TagResponse:
                  $ref: "#/components/examples/TagResponse"
        "409":
          description: Conflict - The target tag already exists in the specified metalake
          content:
            application/vnd.gravitino.v1+json:
              schema:
                $ref: "./openapi.yaml#/components/schemas/ErrorModel"
              examples:
                TagAlreadyExistsException:
                  $ref: "#/components/examples/TagAlreadyExistsException"
        "5xx":
          $ref: "./openapi.yaml#/components/responses/ServerErrorResponse"


  /metalakes/{metalake}/tags/{tag}:
    parameters:
      - $ref: "./openapi.yaml#/components/parameters/metalake"
      - $ref: "./openapi.yaml#/components/parameters/tag"

    get:
      tags:
        - tag
      summary: Get tag
      operationId: getTag
      description: Returns the specified tag information in the specified metalake
      responses:
        "200":
          description: Returns the tag object
          content:
            application/vnd.gravitino.v1+json:
              schema:
                $ref: "#/components/responses/TagResponse"
                examples:
                  TagResponse:
                    $ref: "#/components/examples/TagResponse"
        "404":
          description: Not Found - The specified tag does not exist in the specified metalake
          content:
            application/vnd.gravitino.v1+json:
              schema:
                $ref: "./openapi.yaml#/components/schemas/ErrorModel"
              examples:
                NoSuchMetalakeException:
                  $ref: "./metalakes.yaml#/components/examples/NoSuchMetalakeException"
                NoSuchTagException:
                  $ref: "#/components/examples/NoSuchTagException"
        "5xx":
          $ref: "./openapi.yaml#/components/responses/ServerErrorResponse"

    put:
      tags:
        - tag
      summary: Update tag
      operationId: alterTag
      description: Alters the specified tag information in the specified metalake
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/requests/TagUpdatesRequest"
      responses:
        "200":
            description: Returns the updated tag object
            content:
              application/vnd.gravitino.v1+json:
                schema:
                  $ref: "#/components/responses/TagResponse"
                examples:
                  TagResponse:
                    $ref: "#/components/examples/TagResponse"
        "404":
          description: Not Found - The specified tag does not exist in the specified metalake
          content:
            application/vnd.gravitino.v1+json:
              schema:
                $ref: "./openapi.yaml#/components/schemas/ErrorModel"
              examples:
                NoSuchMetalakeException:
                  $ref: "./metalakes.yaml#/components/examples/NoSuchMetalakeException"
                NoSuchTagException:
                  $ref: "#/components/examples/NoSuchTagException"
        "5xx":
          $ref: "./openapi.yaml#/components/responses/ServerErrorResponse"

    delete:
      tags:
        - tag
      summary: Delete tag
      operationId: deleteTag
      responses:
        "200":
          $ref: "./openapi.yaml#/components/responses/DropResponse"
        "400":
          $ref: "./openapi.yaml#/components/responses/BadRequestErrorResponse"
        "5xx":
          $ref: "./openapi.yaml#/components/responses/ServerErrorResponse"


  /metalakes/{metalake}/objects/{metadataObjectType}/{metadataObjectFullName}/tags:
    parameters:
      - $ref: "./openapi.yaml#/components/parameters/metalake"
      - $ref: "./openapi.yaml#/components/parameters/metadataObjectType"
      - $ref: "./openapi.yaml#/components/parameters/metadataObjectFullName"
    get:
      tags:
        - tag
      summary: List tags (names) for metadata object
      operationId: listObjectTags
      parameters:
        - $ref: "#/components/parameters/details"
      responses:
        "200":
          description: Returns the list of tag objects associated with specified metadata object if {details} is true, otherwise returns the list of tag name
          content:
            application/vnd.gravitino.v1+json:
              schema:
                oneOf:
                  - $ref: "./openapi.yaml#/components/schemas/NameListResponse"
                  - $ref: "#/components/responses/TagListResponse"
              examples:
                NameListResponse:
                  $ref: "#/components/examples/NameListResponse"
                TagListResponse:
                  $ref: "#/components/examples/TagListResponse"
        "400":
          $ref: "./openapi.yaml#/components/responses/BadRequestErrorResponse"
        "404":
          description: Not Found - The specified metalake does not exist
          content:
            application/vnd.gravitino.v1+json:
              schema:
                $ref: "./openapi.yaml#/components/schemas/ErrorModel"
              examples:
                NoSuchMetalakeException:
                  $ref: "./metalakes.yaml#/components/examples/NoSuchMetalakeException"
        "5xx":
          $ref: "./openapi.yaml#/components/responses/ServerErrorResponse"

    post:
      tags:
        - tag
      summary: Associate tags with metadata object
      description: Associate and disassociate tags with metadata object, please be aware that supported metadata objects are CATALOG, SCHEMA, TABLE, FILESET, TOPIC, COLUMN
      operationId: associateTags
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/requests/TagsAssociateRequest"
            examples:
              TagAssociate:
                $ref: "#/components/examples/TagAssociate"
      responses:
        "200":
          description: Returns the list of tag names associated with the specified metadata object
          content:
            application/vnd.gravitino.v1+json:
              schema:
                $ref: "./openapi.yaml#/components/schemas/NameListResponse"
              examples:
                NameListResponse:
                  $ref: "#/components/examples/NameListResponse"
        "404":
          description: Not Found - The specified metalake does not exist
          content:
            application/vnd.gravitino.v1+json:
              schema:
                $ref: "./openapi.yaml#/components/schemas/ErrorModel"
              examples:
                NoSuchMetalakeException:
                  $ref: "./metalakes.yaml#/components/examples/NoSuchMetalakeException"
        "409":
          description: Conflict - The target tag already associated with the specified metadata object
          content:
            application/vnd.gravitino.v1+json:
              schema:
                $ref: "./openapi.yaml#/components/schemas/ErrorModel"
              examples:
                TagAlreadyAssociatedException:
                  $ref: "#/components/examples/TagAlreadyAssociatedException"
        "5xx":
          $ref: "./openapi.yaml#/components/responses/ServerErrorResponse"


  /metalakes/{metalake}/objects/{metadataObjectType}/{metadataObjectFullName}/tags/{tag}:
    parameters:
      - $ref: "./openapi.yaml#/components/parameters/metalake"
      - $ref: "./openapi.yaml#/components/parameters/metadataObjectType"
      - $ref: "./openapi.yaml#/components/parameters/metadataObjectFullName"
      - $ref: "./openapi.yaml#/components/parameters/tag"
    get:
      tags:
        - tag
      summary: Get tag for metadata object
      operationId: getObjectTag
      parameters:
        - $ref: "#/components/parameters/details"
      responses:
        "200":
          description: Returns the list of tag objects associated with specified metadata object if {details} is true, otherwise returns the list of tag name
          content:
            application/vnd.gravitino.v1+json:
              schema:
                $ref: "#/components/responses/TagResponse"
              examples:
                TagResponse:
                  $ref: "#/components/examples/TagResponse"
        "400":
          $ref: "./openapi.yaml#/components/responses/BadRequestErrorResponse"
        "404":
          description: Not Found - The specified metalake does not exist or the specified tag is not associated with the specified metadata object
          content:
            application/vnd.gravitino.v1+json:
              schema:
                $ref: "./openapi.yaml#/components/schemas/ErrorModel"
              examples:
                NoSuchTagException:
                  $ref: "#/components/examples/NoSuchTagException"
                NoSuchMetalakeException:
                  $ref: "./metalakes.yaml#/components/examples/NoSuchMetalakeException"
        "5xx":
          $ref: "./openapi.yaml#/components/responses/ServerErrorResponse"


  /metalakes/{metalake}/tags/{tag}/objects:
    parameters:
      - $ref: "./openapi.yaml#/components/parameters/metalake"
      - $ref: "./openapi.yaml#/components/parameters/tag"
    get:
      tags:
        - tag
      summary: list metadata objects for tag
      operationId: listTagObjects
      responses:
        "200":
          description: Returns the list of metadata objects associated with specified tag
          content:
            application/vnd.gravitino.v1+json:
              schema:
                $ref: "#/components/responses/MetadataObjectListResponse"
              examples:
                TagResponse:
                  $ref: "#/components/examples/MetadataObjectListResponse"
        "400":
          $ref: "./openapi.yaml#/components/responses/BadRequestErrorResponse"
        "404":
          description: Not Found - The specified tag does not exist
          content:
            application/vnd.gravitino.v1+json:
              schema:
                $ref: "./openapi.yaml#/components/schemas/ErrorModel"
              examples:
                NoSuchTagException:
                  $ref: "#/components/examples/NoSuchTagException"
        "5xx":
          $ref: "./openapi.yaml#/components/responses/ServerErrorResponse"


components:
  parameters:
    details:
      name: details
      in: query
      description: Include detailed information about the tag
      required: false
      schema:
        type: boolean
        default: false

  schemas:

    Tag:
      type: object
      description: A tag
      required:
        - name
        - audit
      properties:
        name:
          type: string
          description: The name of the tag
        comment:
          type: string
          description: A comment about the tag
          nullable: true
        audit:
          $ref: "./openapi.yaml#/components/schemas/Audit"
        properties:
          type: object
          description: Configured string to string map of properties for the tag
          default: { }
          additionalProperties:
            type: string
        inherited:
          type: boolean
          description: Whether the tag is inherited from the parent metadata object
          nullable: true

    MetadataObject:
      type: object
      description: A metadata object
      properties:
        fullName:
          type: string
          description: The name of the metadata object, separated by dots
        type:
          type: string
          description: The type of the metadata object
          enum:
            - "CATALOG"
            - "SCHEMA"
            - "TABLE"
            - "FILESET"
            - "TOPIC"
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -



