Actions16
- Index Actions
- Vector Actions
- Metadata Actions
- Utility Actions
Vector → Query
AI-generatedOverview
The node enables interaction with Cloudflare Vectorize vector databases, focusing on vector search and management. Specifically, the Vector - Query operation allows users to perform semantic similarity searches by querying vectors similar to a given input vector within a specified index.
This is useful in scenarios such as:
- Semantic search over documents or media represented as vectors.
- Finding nearest neighbors or similar items in recommendation systems.
- Filtering search results based on metadata constraints.
For example, you can provide a query vector representing a user's search intent and retrieve the top K most similar vectors from an index, optionally filtering by metadata or namespace.
Properties
| Name | Meaning |
|---|---|
| Index Name | The name of the Vectorize index to query. Must be lowercase and contain only letters, numbers, and hyphens. |
| Query Vector | The numeric array representing the vector to search for. Must match the dimensionality of the index vectors. |
| Top K | Number of most similar vectors to return. Range: 1-100 normally, or 1-20 if returning vector values or metadata (due to response size considerations). |
| Return Values | Boolean flag indicating whether to include the full vector values in the results. Enabling this increases response size. |
| Return Metadata | Specifies which metadata to return with each result: • None — no metadata returned • Indexed Only — only metadata fields that have indexes (faster) • All — all metadata fields (may be slower) |
| Filter | JSON object specifying metadata filters to apply. Only vectors matching the filter will be considered. Requires metadata indexes to be configured on those properties. |
| Namespace | Optional string to restrict the query to vectors within a specific namespace. Only vectors in this namespace are searched. |
Output
The output JSON contains a query field with the query results. Each result typically includes:
- The matched vector's ID.
- Similarity score or distance metric value.
- Optionally, the vector values if
Return Valuesis true. - Optionally, metadata fields according to the
Return Metadatasetting.
If metadata filtering is applied, only vectors matching the filter criteria appear in the results.
No binary data output is produced by this operation.
Dependencies
- Requires a valid connection configuration to Cloudflare Vectorize service, including an API key credential.
- The node depends on internal utility functions to communicate with the Cloudflare Vectorize API.
- Properly configured vector indexes with matching dimensions must exist.
- Metadata indexes must be created beforehand to enable filtering on metadata properties.
Troubleshooting
- Dimension mismatch error: Occurs if the query vector length does not match the index's vector dimension. Ensure your query vector matches the index configuration.
- Invalid index name: The index name must be lowercase and contain only letters, numbers, and hyphens.
- Empty or malformed filter: Filters must be valid JSON objects and correspond to indexed metadata fields; otherwise, the filter will be ignored or cause errors.
- Too large Top K with values/metadata: Requesting more than 20 results while returning vector values or metadata may lead to performance issues or API limits.
- Namespace not found: If a namespace is specified but does not exist, the query will return no results.
- API authentication errors: Verify that the API key credential is correctly set up and has permissions to access the specified index.