Common Workflows

Open Index Handle

idx = client.indexes.open(
    namespace="demo-namespace",
    index="demo-index",
)

Insert One Record

record_id = idx.records.add(
    id="doc-1",
    properties={"document_id": "doc-1", "text": "hello"},
    vector=[0.1] * 128,
)

Insert Many Records

result = idx.records.add_many(
    [
        {"id": "doc-2", "properties": {"document_id": "doc-2"}, "vector": [0.2] * 128},
        {"id": "doc-3", "properties": {"document_id": "doc-3"}, "vector": [0.3] * 128},
    ],
    on_error="continue",
)

print("inserted:", len(result))
print("error_count:", result.number_errors)
print("failed_records:", result.failed_records)

High-Throughput Batch Helper

with idx.batch.with_size(batch_size=200, max_workers=4, on_error="continue") as batch:
    batch.add(id="doc-10", properties={"document_id": "doc-10"}, vector=[0.1] * 128)
    batch.add(id="doc-11", properties={"document_id": "doc-11"}, vector=[0.2] * 128)

print("error_count:", batch.number_errors)

Nearest Search

search_result = idx.search.nearest(
    vector=[0.1] * 128,
    limit=10,
    filter={"document_id": {"$eq": "doc-1"}},
)

Cluster Search Results

clusters = idx.search.cluster(
    filter={"status": {"$in": ["failed", "failure", "error"]}},
    limit=1000,
    algorithm="dbscan",
    dbscan_min_samples=4,
    distance_metric="cosine",
    representatives_per_cluster=2,
)

for cluster in clusters["clusters"]:
    print(cluster["count"], cluster["summary"])

Rank Local Semantic Outliers

result = idx.search.anomalies(
    filter={"status": {"$eq": "open"}},
    limit=10_000,
    n_neighbors=20,
    top_n=25,
    text_fields=["subject", "description"],
)

for anomaly in result["anomalies"]:
    print(anomaly["uuid"], anomaly["score"], anomaly["percentile"])

Use the ranking to prioritize review. Percentile is relative to this filtered snapshot and is not a probability.

Discover Topics

result = idx.search.topics(
    filter={"status": {"$eq": "open"}},
    limit=10_000,
    text_fields=["subject", "description"],
    metadata_fields=["priority"],
    min_topics=2,
    max_topics=20,
)

for topic in result["topics"]:
    print(topic["label"], topic["count"], topic["text_coverage"])

Topic membership comes from embeddings. Text produces c-TF-IDF terms, while metadata fields add explanatory counts without changing assignments.

Agent Query

Use the agent query for higher-level analysis tasks that may need multiple EigenLake tools, such as schema inspection, filtering, clustering, anomaly detection, topic modeling, or temporal shift.

result = idx.agent.query(
    "Find new serious support-ticket issues this week and explain the top patterns.",
    filter={"status": {"$eq": "open"}},
    limit=5000,
    text_fields=["subject", "description"],
    metadata_fields=["priority", "product"],
)

print(result["result"])

The server runs the agent with safe EigenLake tools only. It does not expose raw database credentials or arbitrary Python execution.

List and Iterate

page = idx.search.list(limit=100, offset=0)
print(page)

for obj in idx.search.iterate(page_size=500):
    print(obj)

Update and Replace

idx.records.update(
    id="doc-1",
    properties={"text": "updated"},
)

idx.records.replace(
    id="doc-1",
    properties={"document_id": "doc-1", "text": "replaced"},
    vector=[0.4] * 128,
)

Delete

idx.records.remove("doc-1")

job = idx.records.remove_many(
    filter={"document_id": {"$in": ["doc-2", "doc-3"]}},
    background=True,
)
print(job)

Index Metadata and Maintenance

print(idx.settings.dimensions())
print(idx.settings.schema())
print(idx.settings.shards())

idx.manage.remove_by_filter(
    filter={"created_at": {"$lt": "2024-01-01T00:00:00Z"}},
    background=True,
)