Cloudflare Vectorize icon

Cloudflare Vectorize

Execute operations against Cloudflare Vectorize vector databases. Supports vector operations (insert, upsert, query), index management, metadata filtering, and can be used as a tool by AI Agents for semantic search and RAG applications.

Actions16

Vector → Query by ID

AI-generated

Overview

This node integrates with Cloudflare Vectorize, a vector database service designed for semantic search and retrieval-augmented generation (RAG) applications. Specifically, the Vector - Query by ID operation allows users to find vectors similar to an existing vector stored in a specified index by referencing that vector's ID.

Use cases include:

  • Finding semantically related documents or items based on an existing vector representation.
  • Enhancing AI agents or chatbots by retrieving contextually relevant information from a vector store.
  • Performing similarity searches where the query vector is already stored, avoiding the need to provide raw vector data.

For example, given a vector ID representing a product description embedding, you can retrieve the top K most similar products in the same index.

Properties

Name Meaning
Index Name The name of the vector index to query. Must be lowercase and contain only letters, numbers, and hyphens.
Vector ID The ID of an existing vector in the index to use as the query vector for similarity search.
Top K Number of most similar vectors to return. Allowed range: 1-100 generally, or 1-20 if returning vector values or metadata (to limit response size). Default is 5.
Return Values Boolean flag indicating whether to include the actual 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 to the query. Only vectors matching the filter will be considered. Requires metadata indexes to be configured on those properties.
Namespace Optional string to restrict the search to vectors within a specific namespace inside the index. If empty, searches across all namespaces.

Output

The output JSON contains a query field with the results of the similarity search. Each result typically includes:

  • The matched vector's ID.
  • Similarity score or distance metric value.
  • Optionally, the vector values if Return Values is true.
  • Optionally, metadata fields according to the Return Metadata setting.

The structure allows downstream nodes or workflows to process the most relevant vectors found by similarity to the referenced vector ID.

If binary data were involved (not applicable here), it would represent raw vector bytes or attachments, but this operation deals purely with JSON vector data.

Dependencies

  • Requires an API key credential for authenticating with the Cloudflare Vectorize service.
  • The node depends on the external Cloudflare Vectorize API endpoints for vector querying.
  • Proper configuration of vector indexes and metadata indexes in Cloudflare Vectorize is necessary for filtering and querying.
  • The user must ensure the vector ID exists in the specified index; otherwise, queries will fail.

Troubleshooting

  • Common issues:

    • Using a non-existent or misspelled Index Name will cause errors.
    • Providing a Vector ID that does not exist in the index will result in no matches or an error.
    • Filters applied without corresponding metadata indexes configured will be ignored or cause failures.
    • Requesting too many results (Top K) when also returning values/metadata may exceed limits (max 20).

  • Error messages:

    • "Unknown resource" or "Unknown vector operation" indicates misconfiguration of resource or operation parameters.
    • API authentication errors suggest invalid or missing API credentials.
    • JSON parsing errors on Filter or other JSON inputs indicate malformed JSON input.

  • Resolutions:

    • Verify index and vector IDs exist in your Cloudflare Vectorize account.
    • Ensure metadata indexes are created before applying filters.
    • Adjust Top K and return options to stay within allowed limits.
    • Validate JSON syntax for filter and vector inputs.
    • Confirm API credentials are correctly set up in n8n.

Links and References

Discussion