openapi-points.ytt.yaml

#@ load("openapi.lib.yml", "response", "reference", "type", "array")

paths:
  /collections/{collection_name}/points/{id}:
    get:
      tags:
        - points
      summary: Get point
      description: Retrieve full information of single point by id
      operationId: get_point
      parameters:
        - name: collection_name
          in: path
          description: Name of the collection to retrieve from
          required: true
          schema:
            type: string
        - name: id
          in: path
          description: Id of the point
          required: true
          schema:
            $ref: "#/components/schemas/ExtendedPointId"
        - name: consistency
          in: query
          description: Define read consistency guarantees for the operation
          required: false
          schema:
            $ref: "#/components/schemas/ReadConsistency"
      responses: #@ response(reference("Record"))

  /collections/{collection_name}/points:
    post:
      tags:
        - points
      summary: Get points
      description: Retrieve multiple points by specified IDs
      operationId: get_points
      requestBody:
        description: List of points to retrieve
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PointRequest"

      parameters:
        - name: collection_name
          in: path
          description: Name of the collection to retrieve from
          required: true
          schema:
            type: string
        - name: consistency
          in: query
          description: Define read consistency guarantees for the operation
          required: false
          schema:
            $ref: "#/components/schemas/ReadConsistency"
      responses: #@ response(array(reference("Record")))

    put:
      tags:
        - points
      summary: Upsert points
      description: Perform insert + updates on points. If point with given ID already exists - it will be overwritten.
      operationId: upsert_points
      requestBody:
        description: Operation to perform on points
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PointInsertOperations"

      parameters:
        - name: collection_name
          in: path
          description: Name of the collection to update from
          required: true
          schema:
            type: string
        - name: wait
          in: query
          description: "If true, wait for changes to actually happen"
          required: false
          schema:
            type: boolean
        - name: ordering
          in: query
          description: "define ordering guarantees for the operation"
          required: false
          schema:
            $ref: "#/components/schemas/WriteOrdering"
      responses: #@ response(reference("UpdateResult"))

  /collections/{collection_name}/points/delete:
    post:
      tags:
        - points
      summary: Delete points
      description: Delete points
      operationId: delete_points
      requestBody:
        description: Operation to perform on points
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PointsSelector"

      parameters:
        - name: collection_name
          in: path
          description: Name of the collection to delete from
          required: true
          schema:
            type: string
        - name: wait
          in: query
          description: "If true, wait for changes to actually happen"
          required: false
          schema:
            type: boolean
        - name: ordering
          in: query
          description: "define ordering guarantees for the operation"
          required: false
          schema:
            $ref: "#/components/schemas/WriteOrdering"
      responses: #@ response(reference("UpdateResult"))

  /collections/{collection_name}/points/vectors:
    put:
      tags:
        - points
      summary: Update vectors
      description: Update specified named vectors on points, keep unspecified vectors intact.
      operationId: update_vectors
      requestBody:
        description: Update named vectors on points
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateVectors"

      parameters:
        - name: collection_name
          in: path
          description: Name of the collection to update from
          required: true
          schema:
            type: string
        - name: wait
          in: query
          description: "If true, wait for changes to actually happen"
          required: false
          schema:
            type: boolean
        - name: ordering
          in: query
          description: "define ordering guarantees for the operation"
          required: false
          schema:
            $ref: "#/components/schemas/WriteOrdering"
      responses: #@ response(reference("UpdateResult"))

  /collections/{collection_name}/points/vectors/delete:
    post:
      tags:
        - points
      summary: Delete vectors
      description: Delete named vectors from the given points.
      operationId: delete_vectors
      requestBody:
        description: Delete named vectors from points
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DeleteVectors"

      parameters:
        - name: collection_name
          in: path
          description: Name of the collection to delete from
          required: true
          schema:
            type: string
        - name: wait
          in: query
          description: "If true, wait for changes to actually happen"
          required: false
          schema:
            type: boolean
        - name: ordering
          in: query
          description: "define ordering guarantees for the operation"
          required: false
          schema:
            $ref: "#/components/schemas/WriteOrdering"
      responses: #@ response(reference("UpdateResult"))

  /collections/{collection_name}/points/payload:
    post:
      tags:
        - points
      summary: Set payload
      description: Set payload values for points
      operationId: set_payload
      requestBody:
        description: Set payload on points
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SetPayload"

      parameters:
        - name: collection_name
          in: path
          description: Name of the collection to set from
          required: true
          schema:
            type: string
        - name: wait
          in: query
          description: "If true, wait for changes to actually happen"
          required: false
          schema:
            type: boolean
        - name: ordering
          in: query
          description: "define ordering guarantees for the operation"
          required: false
          schema:
            $ref: "#/components/schemas/WriteOrdering"
      responses: #@ response(reference("UpdateResult"))
    put:
      tags:
        - points
      summary: Overwrite payload
      description: Replace full payload of points with new one
      operationId: overwrite_payload
      requestBody:
        description: Payload and points selector
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SetPayload"

      parameters:
        - name: collection_name
          in: path
          description: Name of the collection to set from
          required: true
          schema:
            type: string
        - name: wait
          in: query
          description: "If true, wait for changes to actually happen"
          required: false
          schema:
            type: boolean
        - name: ordering
          in: query
          description: "define ordering guarantees for the operation"
          required: false
          schema:
            $ref: "#/components/schemas/WriteOrdering"
      responses: #@ response(reference("UpdateResult"))

  /collections/{collection_name}/points/payload/delete:
    post:
      tags:
        - points
      summary: Delete payload
      description: Delete specified key payload for points
      operationId: delete_payload
      requestBody:
        description: delete payload on points
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DeletePayload"

      parameters:
        - name: collection_name
          in: path
          description: Name of the collection to delete from
          required: true
          schema:
            type: string
        - name: wait
          in: query
          description: "If true, wait for changes to actually happen"
          required: false
          schema:
            type: boolean
        - name: ordering
          in: query
          description: "define ordering guarantees for the operation"
          required: false
          schema:
            $ref: "#/components/schemas/WriteOrdering"
      responses: #@ response(reference("UpdateResult"))

  /collections/{collection_name}/points/payload/clear:
    post:
      tags:
        - points
      summary: Clear payload
      description: Remove all payload for specified points
      operationId: clear_payload
      requestBody:
        description: clear payload on points
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PointsSelector"

      parameters:
        - name: collection_name
          in: path
          description: Name of the collection to clear payload from
          required: true
          schema:
            type: string
        - name: wait
          in: query
          description: "If true, wait for changes to actually happen"
          required: false
          schema:
            type: boolean
        - name: ordering
          in: query
          description: "define ordering guarantees for the operation"
          required: false
          schema:
            $ref: "#/components/schemas/WriteOrdering"
      responses: #@ response(reference("UpdateResult"))
  /collections/{collection_name}/points/batch:
    post:
      tags:
        - points
      summary: Batch update points
      description: Apply a series of update operations for points, vectors and payloads
      operationId: batch_update
      requestBody:
        description: update operations
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateOperations"
      parameters:
        - name: collection_name
          in: path
          description: Name of the collection to apply operations on
          required: true
          schema:
            type: string
        - name: wait
          in: query
          description: "If true, wait for changes to actually happen"
          required: false
          schema:
            type: boolean
        - name: ordering
          in: query
          description: "define ordering guarantees for the operation"
          required: false
          schema:
            $ref: "#/components/schemas/WriteOrdering"
      responses: #@ response(array(reference("UpdateResult")))