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 → Insert

AI-generated

Overview

The Cloudflare Vectorize node enables interaction with Cloudflare's vector database service, focusing on managing vector data for semantic search and retrieval applications. Specifically, the Vector - Insert operation allows users to insert new vectors into a specified vector index. This operation is useful when building or updating a vector database with new embeddings representing text, images, or other data types for similarity search.

Common scenarios include:

  • Adding newly generated embedding vectors from AI models into an existing vector index.
  • Populating a vector database with metadata-enhanced vectors for semantic search.
  • Incrementally expanding a vector index with fresh data points without overwriting existing vectors.

Practical example:

  • After generating text embeddings using an external AI model, you can use this node to insert those vectors into a Cloudflare Vectorize index, associating each vector with an ID, optional metadata (e.g., category tags), and namespaces for logical grouping.

Properties

Name Meaning
Index Name The name of the target vector index where vectors will be inserted. Must be lowercase and contain only letters, numbers, and hyphens.
Vectors A JSON array of vector objects to insert. Each object must include:
• id (string): Unique identifier for the vector.
• values (number array): The vector components.
• Optional metadata (object): Additional key-value pairs describing the vector.
• Optional namespace (string): Logical grouping within the index.

Example of the Vectors property value:

[
  {
    "id": "vector-1",
    "values": [0.1, 0.2, 0.3],
    "metadata": {"category": "example"},
    "namespace": "default"
  }
]

Output

The output JSON contains information about the result of the insert operation:

  • mutationId: A unique identifier for the mutation request confirming the insertion.
  • vectorCount: The number of vectors successfully inserted.

Example output structure:

{
  "mutationId": "some-unique-id",
  "vectorCount": 1
}

This confirms that the vectors were accepted by the Cloudflare Vectorize service.

Dependencies

  • Requires an API authentication credential for Cloudflare Vectorize service configured in n8n.
  • Relies on the Cloudflare Vectorize API endpoint accessible via the provided credentials.
  • The node uses internal utility functions to format vectors and communicate with the Cloudflare Vectorize API.

Troubleshooting

  • Error: Unknown resource or operation — Ensure the Resource is set to "Vector" and Operation to "Insert".
  • Invalid index name — The index name must be lowercase and only contain letters, numbers, and hyphens.
  • Malformed vectors JSON — The vectors input must be valid JSON with required fields (id, values). Check for syntax errors or missing properties.
  • Duplicate vector IDs — Insert operation fails if any vector ID already exists in the index. Use the Upsert operation to overwrite existing vectors.
  • API authentication errors — Verify that the API key credential is correctly configured and has necessary permissions.
  • Dimension mismatch — The vector values array length must match the dimensions defined in the target index.

Links and References

Discussion