query

Use the query operation to search a vector table using a query vector, text, or record ID.

Performs similarity search to find the most similar vectors in the table. Supports filtering by metadata and various distance metrics. It retrieves the IDs, metadata, vectors, and distance values/scores of the most similar items from the given table. For common distance metrics, lower values indicate closer matches.

Notes:

Parameters

Parameter Type Value Range Required Default Description Notes
table_name str Valid vector table identifier Yes No default Name of the vector table to search. Table must exist in the database schema.
query_by dict Exactly one query mode Yes No default Query vector source. Specify exactly one query mode. Use one of text, id, or vector; a dictionary is required.
top_k int > 0 Yes No default Number of most similar results to return. Zero or negative values raise a validation error.
filters Optional[Dict[str, Any]] Object or NULL No None Metadata filters to narrow search results. Must be a dictionary when provided; translated by the QBE helper and applied to metadata.
advanced_options dict Object or NULL No None Runtime search parameters that control the recall/latency trade-off and, where supported, override applicable query defaults. Must be a dictionary when provided. Supports distance metric, target accuracy, and index query parameters.
include_vectors bool true, false No None Include vector values in the response. Defaults to false; set to true only when the caller needs stored vector values.
output_selector list[str] Metadata field names No None Select metadata keys to include for each matching vector. None returns the full metadata object; an empty list projects no metadata.
debug_flags dict Object or NULL No None Debug or tracing flags for detailed logging. Optional; omit unless diagnostics are needed.

query_by fields

Field Type Value Range Required Description Notes
vector list Array of numbers Conditional Search by a query vector. Use for bring-your-own-vector search or when the query vector is already computed.
text str Non-empty string Conditional Search by text. Requires a table with an embedding model. The table’s configured embedding model generates the query vector.
id str Scalar value Conditional Find records matching the provided ID. The ID must exist in the target vector table.

Performance consideration: A text query must first be converted to a query vector using the table’s database embedding model. This inline embedding uses database CPU resources and adds latency before vector search begins. Supplying a precomputed query vector avoids this embedding step.

filters capabilities

Capability Operator / syntax Example
Direct equality field: value {"status":"active"}
Existence $exists {"email":{"$exists":true}}
Equality $eq {"tier":{"$eq":"gold"}}
Inequality $ne {"tier":{"$ne":"bronze"}}
Greater than $gt {"age":{"$gt":40}}
Greater than or equal $gte {"age":{"$gte":41}}
Less than $lt {"age":{"$lt":40}}
Less than or equal $lte {"age":{"$lte":30}}
Inclusive range $between {"age":{"$between":[30,41]}}
Value in a list $in {"tier":{"$in":["gold","silver"]}}
Value not in a list $nin {"tier":{"$nin":["bronze"]}}
Array contains all values $all {"tags":{"$all":["oracle","security"]}}
String prefix $startsWith {"name":{"$startsWith":"Ada"}}
String substring $hasSubstring {"description":{"$hasSubstring":"Oracle"}}
String substring alias $instr {"description":{"$instr":"security"}}
Regular expression $regex {"name":{"$regex":"^Ada.*"}}
SQL LIKE pattern $like {"name":{"$like":"Ada%"}}
Logical AND $and {"$and":[{"status":"active"},{"balance":{"$gt":10000}}]}
Logical OR $or {"$or":[{"tier":"silver"},{"balance":{"$gt":10000}}]}
Logical NOR $nor {"$nor":[{"tier":"gold"},{"tier":"silver"}]}
Negation $not {"status":{"$not":{"$eq":"inactive"}}}
Same array-object match parent[*]: {...} {"addresses[*]":{"city":"Boston","state":"MA"}}
Absolute value $abs {"temperature":{"$abs":{"$gt":40}}}
Round up $ceiling {"temperature":{"$ceiling":{"$lt":20}}}
Round down $floor {"temperature":{"$floor":{"$lte":0}}}
Convert to number $number {"age":{"$number":{"$gt":40}}}
Convert to binary double $double {"price":{"$double":{"$gt":25}}}
Convert to lowercase $lower {"name":{"$lower":"ada lovelace"}}
Convert to uppercase $upper {"name":{"$upper":"GRACE HOPPER"}}
String length $length {"name":{"$length":{"$gt":10}}}
Convert to string $string {"age":{"$string":{"$eq":"30"}}}
Boolean conversion $boolean {"isPreferred":{"$boolean":true}}
JSON data type $type {"location":{"$type":"object"}}
Array/object size $size {"items":{"$size":{"$gte":3}}}
Date conversion $date {"birthDate":{"$date":{"$gte":"2000-01-01"}}}
Timestamp conversion $timestamp {"createdAt":{"$timestamp":{"$lt":"2026-01-01T00:00:00Z"}}}
Spatial proximity $near {"location":{"$near":{"$geometry":{"type":"Point","coordinates":[-122.417,37.783]},"$distance":10,"$unit":"mile"}}}
Spatial intersection $intersects {"location":{"$intersects":{"$geometry":{"type":"Point","coordinates":[-122.417,37.783]}}}}
Spatial containment $within {"location":{"$within":{"$geometry":{"type":"Polygon","coordinates":[[[-123,37],[-122,37],[-122,38],[-123,38],[-123,37]]]}}}}

For more information about the filter syntax, see SODA Filter Specifications.

advanced_options fields

Field Type Value Range Required Description Notes
distance_metric str MANHATTAN, HAMMING, DOT, COSINE, EUCLIDEAN, EUCLIDEAN_SQUARED, JACCARD, L2_SQUARED No Per-query distance metric override, such as COSINE or EUCLIDEAN. Validation is case-insensitive.
accuracy int 0-100 No Target search accuracy. Higher values provide better recall but can make search slower. Use 100 to approximate exact search.
idx_parameters dict Object or NULL No Direct control of index search knobs. Use efsearch only with HNSW indexes and neighbor partition probes only with IVF indexes.

idx_parameters fields

Field Type Value Range Required Description Notes
efsearch int > 0 No HNSW beam width that controls recall. Use this value to specify the maximum number of candidates considered while probing the index. Supported only with HNSW.
neighbor partition probes int > 0 No IVF partition probes. Increasing the number of partitions scanned can improve recall for IVF indexes. Supported only with IVF.
rescore_factor int 1-100 No Controls the number of candidates rescored during search. Use only when quantization is configured when creating the vector table.

For additional context, see Create Vector Indexes and Hybrid Vector Indexes.

Raises InvalidTableNameFormatError is raised when the table name is invalid.

Search by query vector

results = client.query(
    table_name='products',
    query_by={'vector': [0.1, 0.2, 0.3, ...]},
    top_k=10
)
print(results.items[0].id)

Search by text with filtering

results = client.query(
    table_name='products',
    query_by={'text': 'wireless headphones'},
    top_k=5,
    filters={
        '$and': [
            {'category': {'$eq': 'electronics'}},
            {'price': {'$lt': 200}}
        ]
    }
)

Find similar items to an existing product

results = client.query(
    table_name='products',
    query_by={'id': 'prod_12345'},
    top_k=10,
    filters={'category': {'$eq': 'electronics'}}
)

Search an HNSW index with custom runtime options

results = client.query(
    table_name='products',
    query_by={'text': 'laptop'},
    top_k=10,
    advanced_options={
        'distance_metric': 'EUCLIDEAN',
        'accuracy': 95,
        'idx_parameters': {
            'efsearch': 128,
            'rescore_factor': 2
        }
    },
    include_vectors=True,
    output_selector=["category", "price"],
)
print(results)

Return type QueryResponse

Returns QueryResponse with matching results under items. Each item contains id, metadata, distance, and vector when include_vectors=True. Distance scores are lower-is-better for the common distance metrics.

Example response:

{
    "items": [
        {
            "id": "prod_001",
            "metadata": {
                "name": "Aurora Trail Boots",
                "category": "footwear",
                "price": 129.99,
                "color": "midnight blue"
            },
            "vector": null,
            "distance": 0.0
        },
        {
            "id": "prod_008",
            "metadata": {
                "name": "Glacier Insulated Bottle",
                "category": "accessories",
                "price": 34.0,
                "color": "arctic white"
            },
            "vector": null,
            "distance": 0.00393
        }
    ]
}