Queries_
Filter VectorsDB documents by their metadata using the Query class. Discover comparison, string, logical, ordering, and pagination operators.
5 min read
Many list endpoints in Appwrite allow you to filter, sort, and paginate results using queries. Appwrite provides a common set of syntax to build queries.
In VectorsDB, every document stores an embeddings vector and an optional metadata object. The queries on this page filter documents by the fields inside that metadata object. To rank documents by vector similarity instead, see vector search.
Query class
Appwrite SDKs provide a Query class to help you build queries. The Query class has methods for each type of supported query operation.
Building queries
Queries are passed to an endpoint through the queries parameter as an array of query strings, which can be generated using the Query class.
Each query method is logically separated via AND operations. For OR operation, pass multiple values into the query method separated by commas. For example Query.equal('metadata.genre', ['sci-fi', 'drama']) will fetch documents whose genre is sci-fi or drama.
To filter on a field inside the metadata object, reference it with dot notation, such as metadata.genre or metadata.year.
VectorsDB stores metadata as a JSON object, so metadata fields are compared as strings. Pass filter values as strings, even when the stored value is a number. For example, use Query.greaterThan('metadata.year', '2010'), not Query.greaterThan('metadata.year', 2010). Passing a numeric value returns a 400 error.
By default, results are limited to the first 25 items. You can change this through pagination.
A single request accepts up to 100 queries. Because listDocuments sends them in the URL, a long list or a wide vector query can push past the URL length limit. createQuery accepts the same queries in the request body, where that limit does not apply. See Send queries in the request body.
Query operators
Select
The select operator allows you to specify which fields should be returned from a document. This optimizes response size and retrieves only the data you need. Each VectorsDB document has two data fields, embeddings and metadata.
Use selection patterns
| Pattern | Description | Use case |
|---|---|---|
["metadata"] | Metadata object only | Return metadata without the embedding vector |
["embeddings"] | Embedding vector only | Return the stored vector |
["metadata", "embeddings"] | Both data fields | Get the complete document data |
Optimize performance
Optimize response size - Only select the fields you actually need. Embedding vectors are large, so omitting embeddings keeps responses small when you only need metadata.
Reduce database load - Selecting fewer fields reduces database processing time.
Comparison operators
Pass metadata filter values as strings. See Filter metadata with string values.
Equal
Returns document if a metadata field is equal to any value in the provided array.
Not equal
Returns document if a metadata field is not equal to the provided value.
Less than
Returns document if a metadata field is less than the provided value.
Less than or equal
Returns document if a metadata field is less than or equal to the provided value.
Greater than
Returns document if a metadata field is greater than the provided value.
Greater than or equal
Returns document if a metadata field is greater than or equal to the provided value.
Between
Returns document if a metadata field value falls between the two values. The boundary values are inclusive.
Not between
Returns documents if the metadata field value is outside the range defined by the two values. Boundary values are excluded.
Null checks
Is null
Returns documents where the metadata field value is null or absent.
Is not null
Returns documents where the metadata field value is not null.
String operations
Starts with
Returns documents if a metadata string field starts with a substring.
Not starts with
Returns documents if a metadata string field does not start with a substring.
Ends with
Returns documents if a metadata string field ends with a substring.
Not ends with
Returns documents if a metadata string field does not end with a substring.
Contains
Returns documents if a metadata array field contains the specified elements or if a metadata string field contains the specified substring.
Not contains
Returns documents if a metadata array field does not contain the specified elements, or if a metadata string field does not contain the specified substring.
Logical operators
AND
Returns document if it matches all of the nested sub-queries in the array passed in.
OR
Returns document if it matches any of the nested sub-queries in the array passed in.
Ordering
Order results by a top-level document attribute such as $createdAt, $updatedAt, or $id. Ordering by a nested metadata field is not supported.
Order descending
Orders results in descending order by attribute.
Order ascending
Orders results in ascending order by attribute.
Order random
Orders results in random order.
Pagination
Limit
Limits the number of results returned by the query. Used for pagination.
Offset
Offset the results returned by skipping some of the results. Used for pagination.
Cursor after
Places the cursor after the specified document ID. Used for pagination.
Cursor before
Places the cursor before the specified document ID. Used for pagination.
Complex queries
You can create complex queries by combining AND and OR operations. For example, to find documents that are either sci-fi released after 2010 or romance released before 2005:
This example demonstrates how to combine OR and AND operations. The query uses Query.or() to match either condition: sci-fi released after 2010 OR romance released before 2005. Each condition within the OR is composed of two AND conditions, one for the genre and one for the year. The database returns documents that match either of these combined conditions.
Was this page helpful?
Share what worked or what we should fix. Once approved, our agents automatically apply suggested updates to the docs.