Jump to

• Request
• Response

Perform a vector similarity search over the specified vector table.

post

http://localhost:8080/ords/pdbdba/_/db-api/stable/vecdb/vector-tables/{vector_table_name}/query

Perform a vector similarity search using text, a vector or an ID returning the most similar records as well as their distance.

Request

Path Parameters

• vector_table_name(required): string
  The name of the vector table.

Supported Media Types

• application/json

Request Body - application/json ()

Root Schema : schema

Type: object

Show Source

• advancedOptions: object advancedOptions
  Search tuning options such as distance_metric, efsearch, neighbor partition probes, rescore factor, or rescore_factor.
• debugFlags: object VectorDebugFlags
  Debug flags to be used to trace vector modules
• filters: object filters
  QBE-style metadata filters applied over vector table metadata.
• includeVectors: boolean
  indicates whether vector values are included in the response. Defaults to false.
• outputSelector: array outputSelector
  Top-level metadata keys to project in each result. Null returns full metadata; an empty array returns an empty metadata object.
• queryBy(required): object queryBy
  Query by text, vector or id.
• topK(required): number
  The topK nearest results.

{
    "type":"object",
    "required":[
        "queryBy",
        "topK"
    ],
    "properties":{
        "queryBy":{
            "type":"object",
            "description":"Query by text, vector or id."
        },
        "topK":{
            "type":"number",
            "description":"The topK nearest results."
        },
        "includeVectors":{
            "type":"boolean",
            "description":" indicates whether vector values are included in the response. Defaults to false."
        },
        "filters":{
            "type":"object",
            "description":"QBE-style metadata filters applied over vector table metadata."
        },
        "advancedOptions":{
            "type":"object",
            "description":"Search tuning options such as distance_metric, efsearch, neighbor partition probes, rescore factor, or rescore_factor."
        },
        "debugFlags":{
            "$ref":"#/components/schemas/VectorDebugFlags"
        },
        "outputSelector":{
            "type":"array",
            "description":"Top-level metadata keys to project in each result. Null returns full metadata; an empty array returns an empty metadata object.",
            "items":{
                "type":"string"
            }
        }
    },
    "example":{
        "queryBy":{
            "text":"leave policy"
        },
        "topK":5,
        "outputSelector":[
            "tenant",
            "title"
        ],
        "filters":{
            "tenant":"acme",
            "category":{
                "$in":[
                    "hr",
                    "benefits"
                ]
            }
        },
        "advancedOptions":{
            "distance_metric":"COSINE",
            "efsearch":64
        },
        "includeVectors":false
    }
}

Example:

{
    "queryBy":{
        "text":"leave policy"
    },
    "topK":5,
    "outputSelector":[
        "tenant",
        "title"
    ],
    "filters":{
        "tenant":"acme",
        "category":{
            "$in":[
                "hr",
                "benefits"
            ]
        }
    },
    "advancedOptions":{
        "distance_metric":"COSINE",
        "efsearch":64
    },
    "includeVectors":false
}

Nested Schema : advancedOptions

Type: object

Search tuning options such as distance_metric, efsearch, neighbor partition probes, rescore factor, or rescore_factor.

Nested Schema : VectorDebugFlags

Type: object

Debug flags to be used to trace vector modules

Show Source

• VEC_INDEX_CALIBRATION: string
  Allowed Values: [ "low", "medium", "high" ]
• VECIDX_TRANS: string
  Allowed Values: [ "low", "medium", "high" ]
• VECIDX_TRANS_COM: string
  Allowed Values: [ "low", "medium", "high" ]
• VECIDX_TRANS_PJ: string
  Allowed Values: [ "low", "medium", "high" ]
• VECIDX_TRANS_PJ_DWNGRD: string
  Allowed Values: [ "low", "medium", "high" ]
• VECIDX_TRANS_PJ_GROW: string
  Allowed Values: [ "low", "medium", "high" ]
• VECIDX_TRANS_SJ: string
  Allowed Values: [ "low", "medium", "high" ]
• VECIDX_TRANS_SJ_BG: string
  Allowed Values: [ "low", "medium", "high" ]
• VECTOR_INDEX: string
  Allowed Values: [ "low", "medium", "high" ]
• VECTOR_INDEX_FIXED_VIEW: string
  Allowed Values: [ "low", "medium", "high" ]
• VECTOR_INDEX_NEIGHBOR_GRAPH: string
  Allowed Values: [ "low", "medium", "high" ]
• VECTOR_INDEX_NEIGHBOR_GRAPH_APPCHNG: string
  Allowed Values: [ "low", "medium", "high" ]
• VECTOR_INDEX_NEIGHBOR_GRAPH_BUILD: string
  Allowed Values: [ "low", "medium", "high" ]
• VECTOR_INDEX_NEIGHBOR_GRAPH_MEM: string
  Allowed Values: [ "low", "medium", "high" ]
• VECTOR_INDEX_NEIGHBOR_GRAPH_SEARCH: string
  Allowed Values: [ "low", "medium", "high" ]
• VECTOR_INDEX_NEIGHBOR_GRAPH_STATS: string
  Allowed Values: [ "low", "medium", "high" ]
• VECTOR_INDEX_NEIGHBOR_PARTITIONS: string
  Allowed Values: [ "low", "medium", "high" ]
• VECTOR_TRACE: string
  Allowed Values: [ "low", "medium", "high" ]

{
    "type":"object",
    "description":"Debug flags to be used to trace vector modules",
    "properties":{
        "VECTOR_INDEX":{
            "type":"string",
            "enum":[
                "low",
                "medium",
                "high"
            ]
        },
        "VECTOR_INDEX_NEIGHBOR_GRAPH":{
            "type":"string",
            "enum":[
                "low",
                "medium",
                "high"
            ]
        },
        "VECTOR_INDEX_NEIGHBOR_GRAPH_BUILD":{
            "type":"string",
            "enum":[
                "low",
                "medium",
                "high"
            ]
        },
        "VECTOR_INDEX_NEIGHBOR_GRAPH_MEM":{
            "type":"string",
            "enum":[
                "low",
                "medium",
                "high"
            ]
        },
        "VECTOR_INDEX_NEIGHBOR_GRAPH_SEARCH":{
            "type":"string",
            "enum":[
                "low",
                "medium",
                "high"
            ]
        },
        "VECTOR_INDEX_NEIGHBOR_GRAPH_APPCHNG":{
            "type":"string",
            "enum":[
                "low",
                "medium",
                "high"
            ]
        },
        "VECTOR_INDEX_NEIGHBOR_GRAPH_STATS":{
            "type":"string",
            "enum":[
                "low",
                "medium",
                "high"
            ]
        },
        "VECTOR_INDEX_NEIGHBOR_PARTITIONS":{
            "type":"string",
            "enum":[
                "low",
                "medium",
                "high"
            ]
        },
        "VECTOR_INDEX_FIXED_VIEW":{
            "type":"string",
            "enum":[
                "low",
                "medium",
                "high"
            ]
        },
        "VECIDX_TRANS":{
            "type":"string",
            "enum":[
                "low",
                "medium",
                "high"
            ]
        },
        "VECIDX_TRANS_COM":{
            "type":"string",
            "enum":[
                "low",
                "medium",
                "high"
            ]
        },
        "VECIDX_TRANS_PJ":{
            "type":"string",
            "enum":[
                "low",
                "medium",
                "high"
            ]
        },
        "VECIDX_TRANS_PJ_DWNGRD":{
            "type":"string",
            "enum":[
                "low",
                "medium",
                "high"
            ]
        },
        "VECIDX_TRANS_PJ_GROW":{
            "type":"string",
            "enum":[
                "low",
                "medium",
                "high"
            ]
        },
        "VECIDX_TRANS_SJ":{
            "type":"string",
            "enum":[
                "low",
                "medium",
                "high"
            ]
        },
        "VECIDX_TRANS_SJ_BG":{
            "type":"string",
            "enum":[
                "low",
                "medium",
                "high"
            ]
        },
        "VEC_INDEX_CALIBRATION":{
            "type":"string",
            "enum":[
                "low",
                "medium",
                "high"
            ]
        },
        "VECTOR_TRACE":{
            "type":"string",
            "enum":[
                "low",
                "medium",
                "high"
            ]
        }
    }
}

Nested Schema : filters

Type: object

QBE-style metadata filters applied over vector table metadata.

Nested Schema : outputSelector

Type: array

Top-level metadata keys to project in each result. Null returns full metadata; an empty array returns an empty metadata object.

Show Source

• Array of: string

{
    "type":"array",
    "description":"Top-level metadata keys to project in each result. Null returns full metadata; an empty array returns an empty metadata object.",
    "items":{
        "type":"string"
    }
}

Nested Schema : queryBy

Type: object

Query by text, vector or id.

Security

• BasicAuth: http
  Type: http
• BearerAuth: http
  Type: http
• OAuth2: oauth2
  Type: oauth2

Back to Top

Response

Supported Media Types

• application/json
• application/problem+json

200 Response

List of vectors.

Body ()

Root Schema : schema

Type: object

Show Source

• results: array results

{
    "type":"object",
    "properties":{
        "results":{
            "type":"array",
            "items":{
                "$ref":"#/components/schemas/VecDBSearchItem"
            }
        }
    }
}

Nested Schema : results

Type: array

Show Source

• Array of: object VecDBSearchItem

{
    "type":"array",
    "items":{
        "$ref":"#/components/schemas/VecDBSearchItem"
    }
}

Nested Schema : VecDBSearchItem

Type: object

Show Source

• distance: number (double)
• id: string
• metadata: object metadata
• vector: array vector

{
    "type":"object",
    "properties":{
        "id":{
            "type":"string"
        },
        "metadata":{
            "type":"object"
        },
        "vector":{
            "type":"array",
            "items":{
                "type":"number",
                "format":"double"
            }
        },
        "distance":{
            "type":"number",
            "format":"double"
        }
    }
}

Nested Schema : metadata

Type: object

Nested Schema : vector

Type: array

Show Source

• Array of: number(double)

{
    "type":"array",
    "items":{
        "type":"number",
        "format":"double"
    }
}

400 Response

The request body included invalid parameters.

Body ()

Root Schema : ORDSErrorResponse

Type: object

Show Source

• code(required): string
• diagnosticTrace: string
• instance(required): string
• message(required): string
• stackTrace: string
• type(required): string

{
    "type":"object",
    "required":[
        "code",
        "message",
        "type",
        "instance"
    ],
    "properties":{
        "code":{
            "type":"string"
        },
        "message":{
            "type":"string"
        },
        "type":{
            "type":"string"
        },
        "instance":{
            "type":"string"
        },
        "diagnosticTrace":{
            "type":"string"
        },
        "stackTrace":{
            "type":"string"
        }
    }
}

404 Response

The specified vector table does not exists.

Body ()

Root Schema : ORDSErrorResponse

Type: object

Show Source

• code(required): string
• diagnosticTrace: string
• instance(required): string
• message(required): string
• stackTrace: string
• type(required): string

{
    "type":"object",
    "required":[
        "code",
        "message",
        "type",
        "instance"
    ],
    "properties":{
        "code":{
            "type":"string"
        },
        "message":{
            "type":"string"
        },
        "type":{
            "type":"string"
        },
        "instance":{
            "type":"string"
        },
        "diagnosticTrace":{
            "type":"string"
        },
        "stackTrace":{
            "type":"string"
        }
    }
}

Back to Top