localvectordb.client module

Remote interface for LocalVectorDB over HTTP.

This module provides a client interface to interact with a LocalVectorDB server. It implements the same document-focused interface as the new LocalVectorDB class but connects to a remote server via HTTP.

Main Components:

RemoteVectorDB: Client for connecting to a LocalVectorDB server
Document: Document object for remote use
QueryResult: Search result object
MetadataField: Metadata field definition

Examples

Basic usage:

from localvectordb.client import RemoteVectorDB
from localvectordb.core import MetadataField, MetadataFieldType

# Connect to an existing database
db = RemoteVectorDB(
    name="my_database",
    base_url="http://localhost:5000",
    api_key="your_api_key"
)

# Upsert documents
db.upsert(["Document 1", "Document 2"])

# Search for similar documents
results = db.query("search query", k=5)

Creating a new database with metadata schema:

from localvectordb.core import MetadataField, MetadataFieldType

db = RemoteVectorDB(
    name="new_database",
    base_url="http://localhost:5000",
    api_key="your_api_key",
    create_if_not_exists=True,
    metadata_schema={
        'author': MetadataField(type=MetadataFieldType.TEXT, indexed=True),
        'publish_date': MetadataField(type=MetadataFieldType.DATE, indexed=True),
        'tags': MetadataField(type=MetadataFieldType.JSON)
    },
    embedding_model="nomic-embed-text",
    embedding_provider="ollama",
    chunk_size=512,
    chunking_method="sentences",
    chunk_overlap=1
)

Document operations:

# Upsert documents with metadata
docs = ["Python programming guide", "Machine learning tutorial"]
metadata = [
    {"author": "Jane Doe", "publish_date": "2024-01-01", "tags": ["python", "programming"]},
    {"author": "John Smith", "publish_date": "2024-02-01", "tags": ["ml", "ai"]}
]
doc_ids = db.upsert(docs, metadata=metadata)

# Get documents
doc = db.get(doc_ids[0])
docs = db.get(doc_ids)

# Update a document
db.update(doc_ids[0], content="Updated content", metadata={"author": "Jane Smith"})

# Delete documents
db.delete(doc_ids)

Unified search interface:

# Vector search
results = db.query("python programming", search_type="vector", k=5)

# Keyword search
results = db.query("python programming", search_type="keyword", k=5)

# Hybrid search
results = db.query("python programming", search_type="hybrid", k=5, vector_weight=0.5)

# Search with filters
results = db.query(
    "programming guide",
    search_type="vector",
    filters={"author": "Jane Doe", "publish_date": {">=": "2024-01-01"}}
)

MongoDB-like filtering:

# Filter documents by metadata
docs = db.filter(where={"author": "Jane Doe"})

# SQL filtering with ordering and pagination
docs = db.filter(
    where={"publish_date": {"$gte": "2024-01-01"}},
    order_by="publish_date DESC",
    limit=10
)

Note

This client requires a running LocalVectorDB server. The interface is designed to be a drop-in replacement for the local LocalVectorDB, allowing code to work with either local or remote databases with minimal changes.

class localvectordb.client.RemoteQueryBuilder(db: RemoteVectorDB)

Bases: object

Remote query builder that serializes state for server-side execution.

This class provides the same fluent API as the local QueryBuilder but instead of executing queries locally, it sends the complete query state to the server for processing. This eliminates the need for client-side embedding operations.

Parameters:: db (RemoteVectorDB) – The RemoteVectorDB instance to execute queries against

Examples

Basic query with filters:

results = (db.query_builder()
    .search("machine learning")
    .filter("year", gte_=2020)
    .semantic_filter("methodology", "neural networks", threshold=0.8)
    .order_by("relevance", "desc")
    .limit(10)
    .execute())

Initialize the RemoteQueryBuilder.

__init__(db: RemoteVectorDB): Initialize the RemoteQueryBuilder.

clone() → RemoteQueryBuilder: Create a copy of the current builder state.

search(query: str, search_type: str | None = None, vector_weight: float | None = None, score_threshold: float | None = None, columns: List[str] | None = None) → RemoteQueryBuilder

Search the content for query text.

Mirrors localvectordb.query_builder.QueryBuilder.search() so a chain is portable between local and remote backends. The vector_weight is folded into builder-level state (the server reads it per builder, not per clause). score_threshold is serialized on the clause for forward-compatibility but is not currently honored by the server query-builder endpoint.

search_field(field: str, query: str) → RemoteQueryBuilder: Find records where field contains query (case-insensitive for strings).

filter(field: str | None = None, value: Any = None, **kwargs: Any) → RemoteQueryBuilder

Add exact filter conditions.

Accepts the same call forms as localvectordb.query_builder.QueryBuilder.filter(): a positional field/value pair, operator-suffix kwargs (gte_=2020), or plain field=value kwargs. A positional value is serialized as an $eq condition so the server reconstructs an equivalent filter.

semantic_filter(field: str, concept: str, threshold: float = 0.8, metric: str = 'cosine') → RemoteQueryBuilder

Add a semantic filter to the query.

The semantic filtering is performed server-side using the database’s configured embedding provider. The default threshold (0.8) matches the local QueryBuilder.

Parameters:

field (str) – The field to filter on (‘content’ for main text or metadata field name)
concept (str) – The concept to match against
threshold (float) – Minimum similarity score (0.0 to 1.0)
metric (str) – Similarity metric to use (“cosine”, “euclidean”, “dot”)

Returns:

A new builder with the semantic filter added

Return type:

RemoteQueryBuilder

vector(query: str, score_threshold: float | None = None) → RemoteQueryBuilder: Use vector search.

keyword(query: str, score_threshold: float | None = None) → RemoteQueryBuilder: Use keyword search.

hybrid(query: str, vector_weight: float = 0.5, score_threshold: float | None = None) → RemoteQueryBuilder: Use hybrid search with the specified vector weight.

documents(scoring_method: str = 'frequency_boost', scoring_options: dict | None = None) → RemoteQueryBuilder

Return full documents in results (default).

The scoring_method/scoring_options are accepted for signature parity with the local builder but are governed by the server default; the server query-builder endpoint does not read them from the state.

chunks() → RemoteQueryBuilder: Return individual chunks in results with position information.

sections() → RemoteQueryBuilder: Return section-level results.

context(window_size: int = 2) → RemoteQueryBuilder

Return chunks with a surrounding context window.

The window_size is accepted for signature parity but governed by the server default; the server query-builder endpoint does not read a window size from the state.

search_level(level: Literal['chunks', 'sections', 'documents']) → RemoteQueryBuilder: Not supported remotely (no server-side state field for it).

semantic_dedup(threshold: float) → RemoteQueryBuilder: Not supported remotely (no server-side state field for it).

order_by(field: str, direction: str = 'desc') → RemoteQueryBuilder

Add ordering to the query.

The default direction is "desc" to match the local builder.

order_by_score(direction: str = 'desc') → RemoteQueryBuilder: Order results by relevance score.

clear_ordering() → RemoteQueryBuilder: Remove all ordering clauses.

limit(n: int) → RemoteQueryBuilder: Set the maximum number of results.

offset(n: int) → RemoteQueryBuilder: Set the result offset for pagination.

group_by(*fields: str) → RemoteQueryBuilder: Group results by fields.

aggregate(field: str, function: Literal['count', 'sum', 'avg', 'min', 'max', 'std', 'var'], alias: str | None = None) → RemoteQueryBuilder: Add an aggregation to the query.

count_by(field: str = '*', alias: str | None = None) → RemoteQueryBuilder: Count documents/chunks, optionally grouped by field.

sum_by(field: str, alias: str | None = None) → RemoteQueryBuilder: Sum numeric values in a field.

avg_by(field: str, alias: str | None = None) → RemoteQueryBuilder: Calculate the average of numeric values in a field.

min_by(field: str, alias: str | None = None) → RemoteQueryBuilder: Find the minimum value in a field.

max_by(field: str, alias: str | None = None) → RemoteQueryBuilder: Find the maximum value in a field.

with_search_type(search_type: Literal['vector', 'keyword', 'hybrid']) → RemoteQueryBuilder: Set the default search type.

with_vector_weight(weight: float) → RemoteQueryBuilder: Set the vector weight for hybrid search.

with_return_type(return_type: Literal['documents', 'chunks', 'context']) → RemoteQueryBuilder: Set the return type.

to_dict() → Dict[str, Any]: Serialize the builder state to a dictionary.

execute() → List[QueryResult]

Execute the query on the server.

Returns:: The query results
Return type:: List[QueryResult]

async execute_async() → List[QueryResult]

Execute the query on the server asynchronously.

Returns:: The query results
Return type:: List[QueryResult]

count() → int

Get the count of matching results without returning them.

The server query-builder endpoint has no dedicated count, so this executes the query and returns the result count – matching the local builder’s behaviour for search queries.

async count_async() → int: Get the count of matching results asynchronously.

class localvectordb.client.RemoteVectorDB(name: str, base_url: str = 'http://127.0.0.1:5000', api_key: str | None = None, *, create_if_not_exists: bool = True, metadata_schema: Dict[str, MetadataField] | None = None, embedding_provider: str = 'ollama', embedding_model: str = 'nomic-embed-text', embedding_config: Dict[str, Any] | None = None, chunking_method: str = 'sentences', chunk_size: int = 500, chunk_overlap: int = 1, enable_gpu: bool = False, enable_fts: bool = True, sqlite_profile: Literal['balanced', 'fast_ingest', 'read_optimized', 'durable', 'memory_saver'] = 'balanced', sqlite_pragma_overrides: Dict[str, Any] | None = None, request_timeout: int | None = None, authorization_header: str = 'Authorization', max_retries: int = 3, retry_delay: float = 1.0, max_concurrent_requests: int = 5, connection_pool_limits: Limits | None = None)

Bases: TuningMixin, BaseVectorDB

Client for interacting with a LocalVectorDB server.

This client provides the same interface as LocalVectorDB but connects to a remote server via HTTP.

Parameters:

name (str) – Name of the database
base_url (str) – URL of the LocalVectorDB server (e.g., “http://localhost:5000”)
api_key (str, optional) – API key for authentication. If not provided, checks LVDB_API_KEY environment variable. Specify a custom environment variable by passing “$CUSTOM_ENV_VARIABLE” for this parameter.
create_if_not_exists (bool, default=True) – Whether to create the database if it doesn’t exist
metadata_schema (Dict[str, MetadataField], optional) – Schema definition for metadata fields
embedding_provider (str, optional) – Provider for embeddings, by default “ollama”
embedding_model (str, optional) – Model to use for embeddings, by default “nomic-embed-text”
embedding_config (Dict[str, Any], optional) – Configuration for embedding provider
chunking_method (str, optional) – Method for chunking documents, by default “sentences”
chunk_size (int, optional) – Maximum tokens per chunk, by default 500
chunk_overlap (int, optional) – Overlap between consecutive chunks, by default 1. Measured in the unit of chunking_method (sentences, words, lines, characters, paragraphs), NOT tokens — only chunking_method="tokens" shares its unit with chunk_size. Keep it small (e.g. 1-3).
enable_gpu (bool, optional) – Whether to use GPU for FAISS, by default False
enable_fts (bool, optional) – Whether to enable full-text search, by default True
request_timeout (int, optional) – Timeout for HTTP requests
authorization_header (str, default = "Authorization") – The server can be configured to accept alternate headers, and the client can too.
max_retries (int) – Max number of retries for a request
retry_delay (int) – The delay after a failed request before trying again
max_concurrent_requests (int) – How many maximum requests for embeddings
connection_pool_limits (httpx.Limits) – Parameters for the httpx client connection pool

__init__(name: str, base_url: str = 'http://127.0.0.1:5000', api_key: str | None = None, *, create_if_not_exists: bool = True, metadata_schema: Dict[str, MetadataField] | None = None, embedding_provider: str = 'ollama', embedding_model: str = 'nomic-embed-text', embedding_config: Dict[str, Any] | None = None, chunking_method: str = 'sentences', chunk_size: int = 500, chunk_overlap: int = 1, enable_gpu: bool = False, enable_fts: bool = True, sqlite_profile: Literal['balanced', 'fast_ingest', 'read_optimized', 'durable', 'memory_saver'] = 'balanced', sqlite_pragma_overrides: Dict[str, Any] | None = None, request_timeout: int | None = None, authorization_header: str = 'Authorization', max_retries: int = 3, retry_delay: float = 1.0, max_concurrent_requests: int = 5, connection_pool_limits: Limits | None = None)

property embedding_provider: EmbeddingProvider

Return the remote embedding provider instance.

This provider proxies embedding requests to the server, providing API parity with LocalVectorDB while keeping operations server-side.

property metadata_schema: Dict[str, MetadataField]: Return the metadata schema.

property embedding_model: str: Return the embedding model name

property embedding_dimension: int: Return the dimension of the embeddings

property chunk_size: int: Return the maximum tokens per chunk

property chunk_overlap: int: Return the chunk overlap, in the unit of chunking_method (not tokens unless the method is "tokens").

property chunking_method: str: Return the chunking method

property fts_enabled: bool: Return whether full-text search is enabled

get_stats() → Dict[str, Any]: Get database statistics

Insert or update documents in the database

Parameters:

documents (Union[str, List[str]]) – Document text(s) to add
metadata (Optional[Union[Dict[str, Any], List[Dict[str, Any]]]]) – Metadata for documents. Only fields declared in the database’s metadata schema are stored; other fields are dropped (the server logs a warning).
ids (Optional[Union[str, List[str]]]) – Document IDs (auto-generated if not provided)
batch_size (int) – Batch size for processing, by default 100
similarity_threshold (float, optional) – Skip adding any chunks that are more similar than this value. Good for “pre-deduplication”

Returns:

List of document IDs that were upserted

Return type:

List[str]

Insert new documents into the database

Parameters:

documents (Union[str, List[str]]) – Document text(s) to add
metadata (Optional[Union[Dict[str, Any], List[Dict[str, Any]]]]) – Metadata for documents. Only fields declared in the database’s metadata schema are stored; other fields are dropped (the server logs a warning).
ids (Optional[Union[str, List[str]]]) – Document IDs (auto-generated if not provided)
batch_size (int) – Batch size for processing, by default 100
errors (Literal["ignore", "raise"]) – How to handle document ID conflicts, by default “raise”
similarity_threshold (Optional[float]) – Skip chunks that are too similar to existing chunks

Returns:

List of document IDs that were actually inserted

Return type:

List[str]

count(filters: Dict[str, Any] | None = None) → int

Count documents matching filters.

Parameters:: filters (Dict[str, Any], optional) – Metadata filters to apply
Returns:: Number of matching documents
Return type:: int

Insert or update documents from files using file extraction.

Parameters:

file_paths (Union[str, Path, List[Union[str, Path]]]) – Path(s) to files to extract and upsert
metadata (Optional[Union[Dict[str, Any], List[Dict[str, Any]]]]) – Metadata for documents. Will be merged with extracted metadata.
ids (Optional[Union[str, List[str]]]) – Document IDs. If not provided, will use filename without extension.
batch_size (int) – Batch size for processing, by default 100
similarity_threshold (Optional[float]) – Skip chunks that are too similar to existing chunks
extractor_kwargs (Optional[Dict[str, Any]]) – Additional keyword arguments passed to the extractor

Returns:

List of document IDs that were upserted

Return type:

List[str]

Raises:

FileNotFoundError – If any of the specified files don’t exist
ValueError – If extraction fails for any file

Insert new documents from files using file extraction.

Parameters:

file_paths (Union[str, Path, List[Union[str, Path]]]) – Path(s) to files to extract and insert
metadata (Optional[Union[Dict[str, Any], List[Dict[str, Any]]]]) – Metadata for documents. Will be merged with extracted metadata.
ids (Optional[Union[str, List[str]]]) – Document IDs. If not provided, will use filename without extension.
batch_size (int) – Batch size for processing, by default 100
similarity_threshold (Optional[float]) – Skip chunks that are too similar to existing chunks
errors (Literal["ignore", "raise"]) – How to handle document ID conflicts, by default “raise”
extractor_kwargs (Optional[Dict[str, Any]]) – Additional keyword arguments passed to the extractor

Returns:

List of document IDs that were actually inserted

Return type:

List[str]

Raises:

FileNotFoundError – If any of the specified files don’t exist
ValueError – If extraction fails for any file
DuplicateDocumentIDError – If errors=”raise” and document ID conflicts occur

upsert_from_chunks(chunks_by_document: Dict[str, List[Chunk] | List[str]], metadata: Dict[str, Dict[str, Any]] | None = None, batch_size: int | None = None, similarity_threshold: float | None = None) → List[str]

Upsert documents from pre-chunked data.

Parameters:

chunks_by_document (Dict[str, Union[List[Chunk], List[str]]]) – Dictionary mapping document IDs to their chunks. Chunks can be either: - List[Chunk]: Full Chunk objects with position information - List[str]: Simple strings that will be converted to Chunk objects
metadata (Optional[Dict[str, Dict[str, Any]]], default=None) – Dictionary mapping document IDs to their metadata
batch_size (int, default=100) – Number of embeddings to generate at once
similarity_threshold (Optional[float], default=None) – If provided, filters out chunks that are too similar to existing chunks

Returns:

List of document IDs that were upserted

Return type:

List[str]

insert_from_chunks(chunks_by_document: Dict[str, List[Chunk] | List[str]], metadata: Dict[str, Dict[str, Any]] | None = None, batch_size: int | None = None, similarity_threshold: float | None = None, errors: Literal['ignore', 'raise'] = 'raise') → List[str]

Insert documents from pre-chunked data with conflict handling.

Parameters:

chunks_by_document (Dict[str, Union[List[Chunk], List[str]]]) – Dictionary mapping document IDs to their chunks
metadata (Optional[Dict[str, Dict[str, Any]]], default=None) – Dictionary mapping document IDs to their metadata
batch_size (int, default=100) – Number of embeddings to generate at once
similarity_threshold (Optional[float], default=None) – If provided, filters out chunks that are too similar to existing chunks
errors (Literal["ignore", "raise"], default="raise") – How to handle document ID conflicts

Returns:

List of document IDs that were actually inserted

Return type:

List[str]

Raises:

DuplicateDocumentIDError – If a document ID already exists and errors=”raise”

get(ids: str | List[str]) → Document | List[Document]

Retrieve documents by ID

Parameters:: ids (Union[str, List[str]]) – Document ID(s) to retrieve
Returns:: Retrieved document(s)
Return type:: Union[Document, List[Document]]
Raises:: DocumentNotFoundError – If any requested documents are not found

get_chunk_embeddings(chunk_ids: str | List[str]) → ndarray

Get embeddings for existing chunks in the database

Parameters:: chunk_ids (str | List[str]) – The chunks for which to retrieve the embeddings
Return type:: numpy.ndarray

exists(ids: str | List[str]) → bool | List[bool]

Check if documents exist

Parameters:: ids (Union[str, List[str]]) – Document ID(s) to check
Returns:: Existence status for each ID
Return type:: Union[bool, List[bool]]

delete(ids: str | List[str]) → int

Delete documents

Parameters:: ids (Union[str, List[str]]) – Document ID(s) to delete
Returns:: Number of documents deleted
Return type:: int

update(doc_id: str, content: str | None = None, metadata: Dict[str, Any] | None = None) → bool

Update a document’s content and/or metadata

Parameters:

doc_id (str) – Document ID to update
content (Optional[str]) – New content (if None, content is not updated)
metadata (Optional[Dict[str, Any]]) – New metadata (merged with existing)

Returns:

True if document was updated, False if no updates needed (content and metadata already match the database)

Return type:

bool

Raises:

DocumentNotFoundError – Raised if doc_id does not exist.

patch(doc_id: str, ops: List[Dict[str, Any]], *, expect_hash: str | None = None, metadata: Dict[str, Any] | None = None) → PatchResult

Patch a document’s content with find/replace or span-splice ops.

See localvectordb.LocalVectorDB.patch for the contract and op shapes. Raises DocumentNotFoundError (missing), PatchConflictError (stale expect_hash), or PatchError (unmatched/ambiguous/overlapping op).

query(query: str, *, search_type: Literal['vector', 'keyword', 'hybrid'] = 'hybrid', return_type: Literal['documents', 'chunks', 'sections', 'context', 'enriched'] | None = None, search_level: Literal['chunks', 'sections', 'documents', 'fused'] = 'chunks', k: int = 10, score_threshold: float = 0.0, filters: Dict[str, Any] | None = None, vector_weight: float = 0.5, section_weight: float = 0.65, context_window: int = 2, context_unit: str = 'chunks', context_truncate: bool = False, semantic_dedup_threshold: float | None = None, document_scoring_method: Literal['best', 'average', 'frequency_boost'] = 'frequency_boost', document_scoring_options: dict | None = None, reranker: Any | None = None, reranker_config: Dict[str, Any] | None = None, rerank_k: int | None = None) → List[QueryResult]

Unified query interface for all search types

Parameters:

query (str) – Query text
search_type (Literal['vector', 'keyword', 'hybrid']) – Type of search to perform
return_type (Literal['documents', 'chunks', 'context', 'enriched']) – Whether to return full documents, individual chunks, or chunks with context
k (int) – Maximum number of results to return
score_threshold (float) – Minimum score threshold (0-1, higher=better)
filters (Optional[Dict[str, Any]]) – Metadata filters. Filter fields must be declared in the database’s metadata schema; unknown fields or unsupported operators are rejected by the server with an error.
vector_weight (float) – Weight for vector search in hybrid mode (0-1)
context_window (int) – Number of chunks before and after to include when return_type=’context’
semantic_dedup_threshold (Optional[float]) – Similarity threshold for semantic deduplication (0-1, higher=more similar)
document_scoring_method (str) – Method for aggregating chunk scores into document scores
document_scoring_options (dict, optional) – Parameters controlling the various scoring methods

Returns:

Search results with normalized scores

Return type:

List[QueryResult]

query_multi_column(query: str, *, columns: List[str] | None = None, search_type: Literal['vector', 'keyword', 'hybrid'] = 'hybrid', return_type: Literal['documents', 'chunks'] = 'documents', k: int = 10, score_threshold: float = 0.0, filters: Dict[str, Any] | None = None, vector_weight: float = 0.5, document_scoring_method: Literal['best', 'average', 'frequency_boost'] = 'frequency_boost', document_scoring_options: dict | None = None) → List[QueryResult]

Query across multiple columns (main content + embedding-enabled metadata fields)

Parameters:

query (str) – Query text
columns (Optional[List[str]]) – Specific columns to search. If None, searches all embedding-enabled fields plus main content. Use ‘content’ for main document content.
search_type (Literal['vector', 'keyword', 'hybrid']) – Type of search to perform
return_type (Literal['documents', 'chunks']) – Whether to return full documents or individual chunks
k (int) – Maximum number of results to return
score_threshold (float) – Minimum score threshold (0-1, higher=better)
filters (Optional[Dict[str, Any]]) – Metadata filters to apply
vector_weight (float) – Weight for vector search in hybrid mode (0-1)
document_scoring_method (DocumentScoringMethod) – Method for aggregating chunk scores into document scores
document_scoring_options (dict, optional) – Parameters for the scoring method

Returns:

Search results with column attribution

Return type:

List[QueryResult]

filter(where: Dict[str, Any] | None = None, order_by: str | None = None, limit: int | None = None, offset: int = 0) → List[Document]

Filter documents using enhanced metadata filtering

This method now supports advanced MongoDB-style filtering with operators like $gt, $lt, $contains, $exists, etc. Raw SQL support has been removed for security reasons.

Parameters:

where (Optional[Dict[str, Any]]) –
Filter conditions using either simple format or MongoDB-style operators.

Simple format:
```
{"author": "John Doe", "year": 2023}
```
Advanced format with operators:
```
{
    "author": {"$eq": "John Doe"},
    "year": {"$gte": 2020, "$lte": 2024},
    "tags": {"$contains": "python"},
    "rating": {"$in": [4, 5]},
    "$and": [
        {"category": "tech"},
        {"$or": [{"lang": "en"}, {"lang": "es"}]}
    ]
}
```
Supported operators:
- Comparison: $eq, $ne, $gt, $lt, $gte, $lte, $in, $nin
- String: $like, $ilike, $contains, $startswith, $endswith
- Existence: $exists, $not_exists
- Type: $type
- Logical: $and, $or, $not
- JSON: $contains, $not_contains (for JSON fields)
order_by (Optional[str]) – ORDER BY clause (field name with optional ASC/DESC) Examples: “created_at DESC”, “author ASC”, “rating”
limit (Optional[int]) – Maximum number of results
offset (int) – Number of results to skip

Returns:

Filtered documents

Return type:

List[Document]

Examples

Simple filtering:

# Simple equality
docs = db.filter(where={"author": "John Doe"})

# Multiple conditions (AND)
docs = db.filter(where={"author": "John Doe", "year": 2023})

Advanced filtering:

# Range queries
docs = db.filter(where={
    "year": {"$gte": 2020, "$lte": 2024},
    "rating": {"$gt": 4.0}
})

# String operations
docs = db.filter(where={
    "title": {"$contains": "python"},
    "author": {"$startswith": "Dr."}
})

# List operations
docs = db.filter(where={
    "category": {"$in": ["tech", "science"]},
    "tags": {"$contains": "tutorial"}
})

# Logical operations
docs = db.filter(where={
    "$and": [
        {"year": {"$gte": 2020}},
        {"$or": [
            {"author": "John Doe"},
            {"author": "Jane Smith"}
        ]}
    ]
})

# Existence checks
docs = db.filter(where={
    "optional_field": {"$exists": False},
    "required_field": {"$exists": True}
})

Ordering and pagination:

# Order by field
docs = db.filter(
    where={"category": "tech"},
    order_by="created_at DESC",
    limit=10,
    offset=20
)

Notes

All queries are converted to safe parameterized SQL on the server
Field names are validated against the metadata schema
Raw SQL is no longer supported to prevent injection attacks
JSON fields support special operations like $contains

query_builder() → QueryBuilderInterface

Create a new RemoteQueryBuilder for this database.

The RemoteQueryBuilder provides a fluent API for building complex queries that are executed server-side, including semantic filters. It is typed as the shared QueryBuilderInterface, so the same fluent chain is portable to a LocalVectorDB.

Returns:: A new query builder instance (a RemoteQueryBuilder)
Return type:: QueryBuilderInterface

Examples

Basic query with semantic filter:

results = (db.query_builder()
    .search("machine learning")
    .filter("year", gte_=2020)
    .semantic_filter("methodology", "neural networks", threshold=0.8)
    .limit(10)
    .execute())

Complex multi-criteria query:

results = (db.query_builder()
    .search("quantum computing", search_type="hybrid")
    .filter("publication_type", "paper")
    .filter("citations", gte_=50)
    .semantic_filter("approach", "quantum machine learning", threshold=0.75)
    .order_by("publication_date", "desc")
    .limit(25)
    .execute())

save() → None: Save the database (no-op for remote client)

update_metadata_schema(new_schema: str | Dict[str, Any], drop_columns: bool = False, column_mapping: dict | None = None) → Dict[str, Any]

Update the metadata schema for the remote database

This method allows you to add new metadata fields, modify existing ones, or remove fields from the schema. Existing document data is preserved.

Parameters:

new_schema (Union[str, Dict[str, Any]]) – The new metadata schema to apply. Can be: - str: Schema name from common schemas (e.g., ‘research_papers’) - Dict[str, MetadataField]: Complete field definitions - Dict[str, str]: Simple type-only definitions (e.g., {‘field’: ‘text’}) - Dict[str, tuple]: Tuple definitions (type, indexed) or (type, indexed, required) - Dict[str, dict]: Full field configuration objects
drop_columns (bool, default=False) – Whether to actually drop columns that are no longer in the schema. If False, columns are kept but removed from schema for safety.
column_mapping (dict, optional) – Optionally provide a mapping dict with old-column (key) -> new-column (value)

Returns:

Summary of changes made including: - added_fields: List of newly added field names - removed_fields: List of removed field names - modified_fields: List of modified fields with change details - populated_defaults: List of fields where default values were populated - dropped_columns: List of actually dropped columns (if drop_columns=True) - warnings: List of warnings about potential issues - errors: List of any errors encountered

Return type:

Dict[str, Any]

Examples

Add new metadata fields:

new_schema = {
    'category': {'type': 'text', 'indexed': True, 'required': True, 'default_value': 'general'},
    'rating': {'type': 'real', 'default_value': 0.0},
    'tags': {'type': 'json', 'default_value': []}
}

changes = db.update_metadata_schema(new_schema)
print(f"Added fields: {changes['added_fields']}")
print(f"Populated defaults: {changes['populated_defaults']}")

Use shorthand syntax:

new_schema = {
    'category': 'text',  # Simple type
    'priority': ('integer', False, True),  # (type, indexed, required)
    'rating': ('real', True)  # (type, indexed)
}

changes = db.update_metadata_schema(new_schema)

Apply a common schema:

changes = db.update_metadata_schema('research_papers')

Notes

Field names cannot conflict with reserved columns: id, content, content_hash, created_at, updated_at
Removed fields are removed from the schema but columns are kept for data safety
Type changes are recorded but don’t modify existing data (SQLite limitation)
Index changes are applied immediately
Changes are applied in a transaction and rolled back on error

get_metadata_schema_info() → Dict[str, Any]

Get detailed information about the current metadata schema

Returns:: Dictionary containing: - fields: Dict of field definitions - field_count: Number of fields - indexed_fields: List of indexed field names - required_fields: List of required field names - field_types: Summary of field types used
Return type:: Dict[str, Any]

Examples

Get schema information:

schema_info = db.get_metadata_schema_info()
print(f"Total fields: {schema_info['field_count']}")
print(f"Indexed fields: {schema_info['indexed_fields']}")
print(f"Required fields: {schema_info['required_fields']}")
print(f"Field types: {schema_info['field_types']}")

# Detailed field information
for field_name, field_info in schema_info['fields'].items():
    print(f"{field_name}: {field_info['type']} "
          f"(indexed={field_info['indexed']}, required={field_info['required']})")

property healthy: bool

Check if the remote database server is healthy and accessible.

This property performs a lightweight ping to the server to verify connectivity and server responsiveness. Results are cached for 60 seconds to avoid excessive network requests.

Returns:: True if server is healthy and accessible, False otherwise
Return type:: bool

property closed: bool

Check if the connection to the remote database is closed.

Note: This is a legacy property name. For checking server health, use the ‘healthy’ property instead.

Returns:: False (remote connections don’t have a traditional “closed” state)
Return type:: bool

ping(force: bool = False) → bool: Check if the database is accessible. Override in subclasses.

close() → None: Close the database connection and HTTP clients

classmethod database_exists(db_name: str, base_url: str = 'http://127.0.0.1:5000', api_key: str | None = None, authorization_header: str = 'Authorization') → bool: Check if a database exists on the server

async get_stats_async() → Dict[str, Any]: Get database statistics

Insert or update documents in the database

Parameters:

documents (Union[str, List[str]]) – Document text(s) to add
metadata (Optional[Union[Dict[str, Any], List[Dict[str, Any]]]]) – Metadata for documents. Only fields declared in the database’s metadata schema are stored; other fields are dropped (the server logs a warning).
ids (Optional[Union[str, List[str]]]) – Document IDs (auto-generated if not provided)
batch_size (int) – Batch size for processing, by default 100
similarity_threshold (float, optional) – If provided, skip chunks which have semantic similarity greater than this value (pre-deduplication)

Returns:

List of document IDs that were upserted

Return type:

List[str]

Insert new documents into the database

Parameters:

documents (Union[str, List[str]]) – Document text(s) to add
metadata (Optional[Union[Dict[str, Any], List[Dict[str, Any]]]]) – Metadata for documents. Only fields declared in the database’s metadata schema are stored; other fields are dropped (the server logs a warning).
ids (Optional[Union[str, List[str]]]) – Document IDs (auto-generated if not provided)
batch_size (int) – Batch size for processing, by default 100
errors (Literal["ignore", "raise"]) – How to handle document ID conflicts, by default “raise”
similarity_threshold (Optional[float]) – Skip chunks that are too similar to existing chunks

Returns:

List of document IDs that were actually inserted

Return type:

List[str]

Insert or update documents from files using file extraction (async).

Parameters:

file_paths (Union[str, Path, List[Union[str, Path]]]) – Path(s) to files to extract and upsert
metadata (Optional[Union[Dict[str, Any], List[Dict[str, Any]]]]) – Metadata for documents. Will be merged with extracted metadata.
ids (Optional[Union[str, List[str]]]) – Document IDs. If not provided, will use filename without extension.
batch_size (int) – Batch size for processing, by default 100
similarity_threshold (Optional[float]) – Skip chunks that are too similar to existing chunks
extractor_kwargs (Optional[Dict[str, Any]]) – Additional keyword arguments passed to the extractor

Returns:

List of document IDs that were upserted

Return type:

List[str]

Raises:

FileNotFoundError – If any of the specified files don’t exist
ValueError – If extraction fails for any file

Insert new documents from files using file extraction (async).

Parameters:

file_paths (Union[str, Path, List[Union[str, Path]]]) – Path(s) to files to extract and insert
metadata (Optional[Union[Dict[str, Any], List[Dict[str, Any]]]]) – Metadata for documents. Will be merged with extracted metadata.
ids (Optional[Union[str, List[str]]]) – Document IDs. If not provided, will use filename without extension.
batch_size (int) – Batch size for processing, by default 100
similarity_threshold (Optional[float]) – Skip chunks that are too similar to existing chunks
errors (Literal["ignore", "raise"]) – How to handle document ID conflicts, by default “raise”
max_concurrent_chunks (int) – Maximum concurrent chunk processing (unused for remote)
max_concurrent_embeddings (int) – Maximum concurrent embedding requests (unused for remote)
extractor_kwargs (Optional[Dict[str, Any]]) – Additional keyword arguments passed to the extractor

Returns:

List of document IDs that were actually inserted

Return type:

List[str]

Raises:

FileNotFoundError – If any of the specified files don’t exist
ValueError – If extraction fails for any file
DuplicateDocumentIDError – If errors=”raise” and document ID conflicts occur

async upsert_from_chunks_async(chunks_by_document: Dict[str, List[Chunk] | List[str]], metadata: Dict[str, Dict[str, Any]] | None = None, batch_size: int | None = None, similarity_threshold: float | None = None, max_concurrent_chunks: int = 3, max_concurrent_embeddings: int = 2) → List[str]

Upsert documents from pre-chunked data (async).

Parameters:

chunks_by_document (Dict[str, Union[List[Chunk], List[str]]]) – Dictionary mapping document IDs to their chunks. Chunks can be either: - List[Chunk]: Full Chunk objects with position information - List[str]: Simple strings that will be converted to Chunk objects
metadata (Optional[Dict[str, Dict[str, Any]]], default=None) – Dictionary mapping document IDs to their metadata
batch_size (int, default=100) – Number of embeddings to generate at once
similarity_threshold (Optional[float], default=None) – If provided, filters out chunks that are too similar to existing chunks
max_concurrent_chunks (int) – Maximum concurrent chunk processing (unused for remote)
max_concurrent_embeddings (int) – Maximum concurrent embedding requests (unused for remote)

Returns:

List of document IDs that were upserted

Return type:

List[str]

async insert_from_chunks_async(chunks_by_document: Dict[str, List[Chunk] | List[str]], metadata: Dict[str, Dict[str, Any]] | None = None, batch_size: int | None = None, similarity_threshold: float | None = None, errors: Literal['ignore', 'raise'] = 'raise', max_concurrent_chunks: int = 3, max_concurrent_embeddings: int = 2) → List[str]

Insert documents from pre-chunked data with conflict handling (async).

Parameters:

chunks_by_document (Dict[str, Union[List[Chunk], List[str]]]) – Dictionary mapping document IDs to their chunks
metadata (Optional[Dict[str, Dict[str, Any]]], default=None) – Dictionary mapping document IDs to their metadata
batch_size (int, default=100) – Number of embeddings to generate at once
similarity_threshold (Optional[float], default=None) – If provided, filters out chunks that are too similar to existing chunks
errors (Literal["ignore", "raise"], default="raise") – How to handle document ID conflicts
max_concurrent_chunks (int) – Maximum concurrent chunk processing (unused for remote)
max_concurrent_embeddings (int) – Maximum concurrent embedding requests (unused for remote)

Returns:

List of document IDs that were actually inserted

Return type:

List[str]

Raises:

DuplicateDocumentIDError – If a document ID already exists and errors=”raise”

async get_async(ids: str | List[str]) → Document | List[Document]

Retrieve documents by ID

Parameters:: ids (Union[str, List[str]]) – Document ID(s) to retrieve
Returns:: Retrieved document(s)
Return type:: Union[Document, List[Document]]

async exists_async(ids: str | List[str]) → bool | List[bool]

Check if documents exist

Parameters:: ids (Union[str, List[str]]) – Document ID(s) to check
Returns:: Existence status for each ID
Return type:: Union[bool, List[bool]]

async delete_async(ids: str | List[str]) → int

Delete documents

Parameters:: ids (Union[str, List[str]]) – Document ID(s) to delete
Returns:: Number of documents deleted
Return type:: int

async count_async(filters: Dict[str, Any] | None = None) → int

Count documents matching filters asynchronously.

Parameters:: filters (Dict[str, Any], optional) – Metadata filters to apply
Returns:: Number of matching documents
Return type:: int

async update_async(doc_id: str, content: str | None = None, metadata: Dict[str, Any] | None = None) → bool

Update a document’s content and/or metadata

Parameters:

doc_id (str) – Document ID to update
content (Optional[str]) – New content (if None, content is not updated)
metadata (Optional[Dict[str, Any]]) – New metadata (merged with existing)

Returns:

True if document was updated, False if no updates needed (content and metadata already match the database)

Return type:

bool

Raises:

DocumentNotFoundError – Raised if doc_id does not exist.

async patch_async(doc_id: str, ops: List[Dict[str, Any]], *, expect_hash: str | None = None, metadata: Dict[str, Any] | None = None) → PatchResult: Patch a document’s content asynchronously. Same contract as patch().

async query_async(query: str, *, search_type: Literal['vector', 'keyword', 'hybrid'] = 'hybrid', return_type: Literal['documents', 'chunks', 'sections', 'context', 'enriched'] | None = None, search_level: Literal['chunks', 'sections', 'documents', 'fused'] = 'chunks', k: int = 10, score_threshold: float = 0.0, filters: Dict[str, Any] | None = None, vector_weight: float = 0.5, section_weight: float = 0.65, context_window: int = 2, context_unit: str = 'chunks', context_truncate: bool = False, semantic_dedup_threshold: float | None = None, document_scoring_method: Literal['best', 'average', 'frequency_boost'] = 'frequency_boost', document_scoring_options: dict | None = None, reranker: Any | None = None, reranker_config: Dict[str, Any] | None = None, rerank_k: int | None = None) → List[QueryResult]

Unified query interface for all search types

Parameters:

query (str) – Query text
search_type (Literal['vector', 'keyword', 'hybrid']) – Type of search to perform
return_type (Literal['documents', 'chunks']) – Whether to return full documents or individual chunks
k (int) – Maximum number of results to return
score_threshold (float) – Minimum score threshold (0-1, higher=better)
filters (Optional[Dict[str, Any]]) – Metadata filters. Filter fields must be declared in the database’s metadata schema; unknown fields or unsupported operators are rejected by the server with an error.
vector_weight (float) – Weight for vector search in hybrid mode (0-1)
context_window (int) – Number of chunks before and after to include when return_type=’context’
semantic_dedup_threshold (Optional[float]) – Similarity threshold for semantic deduplication (0-1, higher=more similar)
document_scoring_method (str) – Method for aggregating chunk scores into document scores
document_scoring_options (dict) – Optional parameters specific to each scoring method

Returns:

Search results with normalized scores

Return type:

List[QueryResult]

async query_multi_column_async(query: str, *, columns: List[str] | None = None, search_type: Literal['vector', 'keyword', 'hybrid'] = 'hybrid', return_type: Literal['documents', 'chunks'] = 'documents', k: int = 10, score_threshold: float = 0.0, filters: Dict[str, Any] | None = None, vector_weight: float = 0.5, document_scoring_method: Literal['best', 'average', 'frequency_boost'] = 'frequency_boost', document_scoring_options: dict | None = None) → List[QueryResult]

Async query across multiple columns (main content + embedding-enabled metadata fields)

Parameters:

query (str) – Query text
columns (Optional[List[str]]) – Specific columns to search. If None, searches all embedding-enabled fields plus main content. Use ‘content’ for main document content.
search_type (Literal['vector', 'keyword', 'hybrid']) – Type of search to perform
return_type (Literal['documents', 'chunks']) – Whether to return full documents or individual chunks
k (int) – Maximum number of results to return
score_threshold (float) – Minimum score threshold (0-1, higher=better)
filters (Optional[Dict[str, Any]]) – Metadata filters to apply
vector_weight (float) – Weight for vector search in hybrid mode (0-1)
document_scoring_method (DocumentScoringMethod) – Method for aggregating chunk scores into document scores
document_scoring_options (dict, optional) – Parameters for the scoring method

Returns:

Search results with column attribution

Return type:

List[QueryResult]

async filter_async(where: Dict[str, Any] | None = None, order_by: str | None = None, limit: int | None = None, offset: int = 0) → List[Document]

Filter documents using enhanced metadata filtering

Parameters:

where (Optional[Dict[str, Any]]) – Filter conditions using either simple format or MongoDB-style operators
order_by (Optional[str]) – ORDER BY clause (field name with optional ASC/DESC)
limit (Optional[int]) – Maximum number of results
offset (int) – Number of results to skip

Returns:

Filtered documents

Return type:

List[Document]

async save_async() → None: No-op for remote databases

async close_async() → None: Close HTTP clients

async update_metadata_schema_async(new_schema: str | Dict[str, Any], drop_columns: bool = False, column_mapping: dict | None = None) → Dict[str, Any]

Update the metadata schema for the database asynchronously

This method allows you to add new metadata fields, modify existing ones, or remove fields from the schema. Existing document data is preserved.

Parameters:

new_schema (Union[str, Dict[str, Any]]) – The new metadata schema to apply. Can be: - str: Schema name from common schemas (e.g., ‘research_papers’) - Dict with field definitions
drop_columns (bool, default=False) – Whether to actually drop columns that are no longer in the schema. If False, columns are kept but removed from schema for safety.
column_mapping (dict, optional) – Optionally provide a mapping dict with old-column (key) -> new-column (value)

Returns:

Summary of changes made including: - added_fields: List of newly added field names - removed_fields: List of removed field names - modified_fields: List of modified fields with change details - populated_defaults: List of fields where default values were populated - dropped_columns: List of actually dropped columns (if drop_columns=True) - warnings: List of warnings about potential issues - errors: List of any errors encountered

Return type:

Dict[str, Any]

Examples

Add new metadata fields:

new_schema = {
    'category': {
        'type': 'text',
        'indexed': True
    },
    'priority': {
        'type': 'integer',
        'default_value': 0
    }
}

changes = await db.update_metadata_schema_async(new_schema)
print(f"Added fields: {changes['added_fields']}")

Apply a common schema:

changes = await db.update_metadata_schema_async('research_papers')

async get_metadata_schema_info_async() → Dict[str, Any]

Get detailed information about the current metadata schema asynchronously

Returns:: Dictionary containing: - fields: Dict of field definitions - field_count: Number of fields - indexed_fields: List of indexed field names - required_fields: List of required field names - field_types: Summary of field types used
Return type:: Dict[str, Any]

Examples

Get schema information:

schema_info = await db.get_metadata_schema_info_async()
print(f"Total fields: {schema_info['field_count']}")
print(f"Indexed fields: {schema_info['indexed_fields']}")
print(f"Required fields: {schema_info['required_fields']}")
print(f"Field types: {schema_info['field_types']}")

# Detailed field information
for field_name, field_info in schema_info['fields'].items():
    print(f"{field_name}: {field_info['type']} "
          f"(indexed={field_info['indexed']}, required={field_info['required']})")

get_sqlite_tuning() → Dict[str, Any]: Get current SQLite tuning configuration from remote server.

set_sqlite_tuning(profile: str, overrides: Dict[str, Any] | None = None, persist: bool = True) → None: Apply SQLite tuning profile via remote server.

auto_tune(workload: Dict[str, Any] | None = None, interactive: bool = False, apply: bool = False) → Dict[str, Any]

Get auto-tuning recommendations from the remote server.

The recommendation is computed on the server (from the server’s own system resources), not the client machine. interactive is not supported over HTTP – pass an explicit workload dict instead.

sqlite_checkpoint(mode: str = 'PASSIVE') → None: Run SQLite WAL checkpoint via remote server.

sqlite_optimize() → None: Run SQLite PRAGMA optimize via remote server.

sqlite_vacuum() → None: Run SQLite VACUUM via remote server.

sqlite_incremental_vacuum(pages: int = 2000) → None: Run incremental VACUUM via remote server.

analyze_system_resources() → Dict[str, Any]: Analyze remote server system resources.

checkpoint_if_wal_large(wal_mb_threshold: int = 128) → bool: Check if remote WAL is large and checkpoint if needed.

query_stream(query: str, *, search_type: str = 'hybrid', return_type: str = 'documents', k: int = 10, score_threshold: float = 0.0, filters: Dict[str, Any] | None = None, vector_weight: float = 0.5, batch_size: int = 10, context_window: int = 2, context_unit: str = 'chunks', context_truncate: bool = False, document_scoring_method: str = 'frequency_boost', document_scoring_options: Dict[str, Any] | None = None)

Stream query results from the server via SSE.

Yields lists of QueryResult objects as they arrive from the server.

Parameters:

query (str) – The search query text.
search_type (str) – One of ‘vector’, ‘keyword’, ‘hybrid’.
return_type (str) – One of ‘documents’, ‘chunks’, ‘context’, ‘enriched’.
k (int) – Maximum number of results.
batch_size (int) – Number of results per SSE batch.

Yields:

List[QueryResult] – Batches of query results as they stream from the server.

async query_stream_async(query: str, *, search_type: str = 'hybrid', return_type: str = 'documents', k: int = 10, score_threshold: float = 0.0, filters: Dict[str, Any] | None = None, vector_weight: float = 0.5, batch_size: int = 10, context_window: int = 2, context_unit: str = 'chunks', context_truncate: bool = False, document_scoring_method: str = 'frequency_boost', document_scoring_options: Dict[str, Any] | None = None): Async version of query_stream. Yields lists of QueryResult.

compare_documents(doc_id_1: str, doc_id_2: str) → float

Compare two documents and return their similarity score.

Parameters:

doc_id_1 (str) – First document ID.
doc_id_2 (str) – Second document ID.

Returns:

Similarity score between the two documents.

Return type:

float

async compare_documents_async(doc_id_1: str, doc_id_2: str) → float: Async version of compare_documents.

compare_documents_detailed(doc_id_1: str, doc_id_2: str, chunk_threshold: float = 0.7) → DocumentComparisonResult

Compare two documents with detailed chunk-level analysis.

Parameters:

doc_id_1 (str) – First document ID.
doc_id_2 (str) – Second document ID.
chunk_threshold (float) – Threshold for chunk-level similarity matching.

Returns:

Detailed comparison result with per-chunk alignments.

Return type:

DocumentComparisonResult

async compare_documents_detailed_async(doc_id_1: str, doc_id_2: str, chunk_threshold: float = 0.7) → DocumentComparisonResult: Async version of compare_documents_detailed.

nearest_neighbors(doc_id: str, k: int = 5, score_threshold: float = 0.0, filters: Dict[str, Any] | None = None) → List[QueryResult]

Find nearest neighbors for a document.

Parameters:

doc_id (str) – The document ID to find neighbors for.
k (int) – Number of neighbors to return.
score_threshold (float) – Minimum similarity score to include.
filters (dict, optional) – Metadata filter applied to candidate documents.

Returns:

List of nearest neighbor results.

Return type:

List[QueryResult]

async nearest_neighbors_async(doc_id: str, k: int = 5, score_threshold: float = 0.0, filters: Dict[str, Any] | None = None) → List[QueryResult]: Async version of nearest_neighbors.

pairwise_similarity_matrix(doc_ids: List[str] | None = None) → DocumentSimilarityMatrix

Compute pairwise similarity matrix for documents.

Parameters:: doc_ids (Optional[List[str]]) – Document IDs to include. If None, uses all documents.
Returns:: Matrix with similarity scores between all document pairs.
Return type:: DocumentSimilarityMatrix

async pairwise_similarity_matrix_async(doc_ids: List[str] | None = None) → DocumentSimilarityMatrix: Async version of pairwise_similarity_matrix.