Create a new Zvec collection and open it for use.

This tool creates a new vector database collection at the specified path with the given schema definition. The collection is automatically opened and cached for subsequent operations. Use this when you need to initialize a new vector database.

Args: params (CreateCollectionInput): Validated input parameters containing: - path (str): Filesystem path where collection will be created (e.g., './my_vectors') - collection_name (str): Name of the collection (also used as unique session key) - vector_fields (List[VectorFieldInput]): Vector field definitions (required, min 1); each field may include an optional index_param to auto-create its index - scalar_fields (Optional[List[ScalarFieldInput]]): Scalar field definitions; each field may also include an optional index_param

Returns: str: Success message with collection details or error message

Examples: - Use when: "Create a new collection for storing document embeddings" - Use when: "Initialize a vector database at ./embeddings with 768-dim vectors" - Don't use when: Collection already exists (use open_collection instead)

Open an existing Zvec collection from disk.

This tool opens a previously created collection and caches it for subsequent operations. The collection must have been created with zvec_create_and_open_collection.

Args: params (OpenCollectionInput): Validated input parameters containing: - path (str): Filesystem path of the existing collection - collection_name (str): Unique session identifier for caching - read_only (bool): Open in read-only mode (default: False)

Returns: str: Success message with collection details or error message

Examples: - Use when: "Open the collection at ./my_vectors" - Use when: "Load existing vector database from ./embeddings" - Don't use when: Collection doesn't exist (use create_and_open_collection)

Get detailed information about an opened collection.

Retrieves schema definition, statistics, and configuration of a collection.

Args: params (GetCollectionInfoInput): Validated input parameters containing: - collection_name (str): Collection identifier - response_format (ResponseFormat): Output format ('markdown' or 'json')

Returns: str: Collection information in the requested format or error message

Permanently delete a collection from disk.

WARNING: This operation is irreversible. All data will be permanently lost.

Args: params (DestroyCollectionInput): Validated input parameters containing: - collection_name (str): Collection identifier

Returns: str: Success confirmation or error message

Insert new documents into a collection.

Documents must have unique IDs and conform to the collection schema. This operation fails if a document with the same ID already exists.

Args: params (InsertDocumentsInput): Validated input parameters containing: - collection_name (str): Collection identifier - documents (List[DocumentInput]): Documents to insert

Returns: str: Success message with insertion count or error message

Insert new documents or update existing ones by ID.

This operation inserts documents if they don't exist, or updates them if they do.

Args: params (UpsertDocumentsInput): Validated input parameters containing: - collection_name (str): Collection identifier - documents (List[DocumentInput]): Documents to upsert

Returns: str: Success message with upsert count or error message

Update existing documents by ID.

Only specified fields are updated; others remain unchanged. Documents must already exist.

Args: params (UpdateDocumentsInput): Validated input parameters containing: - collection_name (str): Collection identifier - documents (List[DocumentInput]): Documents with updates

Returns: str: Success message with update count or error message

Delete documents by their IDs.

Args: params (DeleteDocumentsInput): Validated input parameters containing: - collection_name (str): Collection identifier - document_ids (List[str]): Document IDs to delete

Returns: str: Success message with deletion count or error message

Retrieve documents by their IDs.

Args: params (FetchDocumentsInput): Validated input parameters containing: - collection_name (str): Collection identifier - document_ids (List[str]): Document IDs to fetch - response_format (ResponseFormat): Output format

Returns: str: Documents in the requested format or error message

Perform vector similarity search with optional filtering.

This tool searches for the most similar documents based on vector similarity. Optionally apply scalar filters to restrict results to a subset of documents.

Args: params (VectorQueryInput): Validated input parameters containing: - collection_name (str): Collection identifier - field_name (str): Name of the vector field to query - vector (List[float]): Query vector - topk (int): Number of results to return (default: 10, max: 1000) - filter (Optional[str]): Filter expression (e.g., 'age > 25 AND city == "NYC"') - response_format (ResponseFormat): Output format

Returns: str: Search results sorted by similarity score or error message

Examples: - Use when: "Find the 10 most similar documents to this embedding" - Use when: "Search for similar vectors with age > 30" - Filter syntax: "field_name > value", "field == 'string'", combined with AND/OR

Perform multi-vector similarity search with score fusion and re-ranking.

This tool searches across multiple vector embeddings simultaneously and combines their results using a re-ranking strategy. This is useful when documents have multiple types of embeddings (e.g., dense + sparse, text + image).

Args: params (MultiVectorQueryInput): Validated input parameters containing: - collection_name (str): Collection identifier - vectors (List[MultiVectorQuerySpec]): List of vector queries (min 2) - topk (int): Candidates to retrieve from each vector field (default: 10) - topn (int): Final documents to return after re-ranking (default: 5) - reranker_type (str): 'weighted' or 'rrf' (default: weighted) - weights (Optional[Dict[str, float]]): Field weights for weighted re-ranker - rank_constant (int): RRF rank constant (default: 60) - metric_type (str): Metric for weighted re-ranker (default: IP) - filter (Optional[str]): Filter expression - response_format (str): Output format

Returns: str: Re-ranked search results or error message

Examples: - Use when: "Search using both dense and sparse embeddings" - Use when: "Combine text and image similarity for multi-modal search"

Re-ranking Strategies: - Weighted: Combines normalized scores with custom weights per field Best when scores are comparable and you know field importance - RRF (Reciprocal Rank Fusion): Combines based on rank positions only Best when scores use different metrics/scales or prefer tuning-free approach

Create an index on a field to accelerate queries.

Use HnswIndexParamInput / FlatIndexParamInput / IVFIndexParamInput for vector fields, and InvertIndexParamInput for scalar fields.

Args: params (CreateIndexInput): Validated input parameters containing: - collection_name (str): Collection identifier - field_name (str): Name of the field to index - index_param: One of HnswIndexParamInput, FlatIndexParamInput, IVFIndexParamInput, or InvertIndexParamInput (use 'type' field as discriminator)

Returns: str: Success message or error message

Examples: - Use when: "Create an HNSW index on the embedding field" - Use when: "Build an inverted index on the category scalar field"

Remove the index from a field.

Args: params (DropIndexInput): Validated input parameters containing: - collection_name (str): Collection identifier - field_name (str): Name of the indexed field

Returns: str: Success message or error message

Optimize the collection (e.g., merge segments, rebuild index).

This operation improves query performance and reduces storage overhead.

Args: params (OptimizeCollectionInput): Validated input parameters containing: - collection_name (str): Collection identifier

Returns: str: Success message or error message

Generate a dense embedding vector for a piece of text using OpenAIDenseEmbedding.

Converts text into a fixed-length dense vector via the OpenAI (or compatible) embedding API. The resulting vector can be directly used for similarity search.

Args: params (GenerateDenseEmbeddingInput): - text: Text to embed - api_key: OpenAI API key (or OPENAI_API_KEY env var) - base_url: Custom API base URL for OpenAI-compatible endpoints - model: Embedding model name (default: text-embedding-3-small) - dimension: Output vector dimension (default: 1536)

Returns: str: JSON with text preview, model, dimension, and the dense vector

Embed text documents and upsert them into a Zvec collection.

Converts each document's text field to a dense vector using OpenAIDenseEmbedding, then upserts all documents into the specified collection. This is the high-level write interface: supply plain text, get vectors stored automatically.

OpenAI connection is read from environment variables: OPENAI_API_KEY, OPENAI_BASE_URL (optional), OPENAI_EMBEDDING_MODEL (optional). The embedding dimension is inferred from the collection schema automatically.

Args: params (EmbeddingWriteInput): - collection_name: Target collection - field_name: Vector field to populate - documents: List of {id, text, fields} — text is auto-embedded

Returns: str: Success message with upsert count, or error

Convert a natural language query to a vector and perform similarity search.

Embeds query_text using OpenAIDenseEmbedding, then runs a vector similarity search against the specified field in the collection. This is the high-level search interface: supply a natural language query, get ranked results.

OpenAI connection is read from environment variables: OPENAI_API_KEY, OPENAI_BASE_URL (optional), OPENAI_EMBEDDING_MODEL (optional). The embedding dimension is inferred from the collection schema automatically.

Args: params (EmbeddingSearchInput): - collection_name: Target collection - field_name: Vector field to search - query_text: Natural language query to embed and search with - topk: Number of results (default: 10) - filter: Optional scalar filter expression - response_format: Output format ('markdown' or 'json')

Returns: str: Search results sorted by similarity, or error