Table Operations

Reading, writing, and managing data in Clarifeye tables

Table Operations

Manage data in your Clarifeye tables using the Table class methods. This includes writing data, reading data, and pushing data to the retrieval system for search operations.

Write Data

Write data to a table:

warehouse = client.get_warehouse("warehouse-id")
table = warehouse.get_table("my-table")

# Write multiple records
data = [
    {"id": "1", "name": "John Doe", "email": "[e-mail]"},
    {"id": "2", "name": "Jane Smith", "email": "[e-mail]"},
    {"id": "3", "name": "Bob Johnson", "email": "[e-mail]"}
]

result = table.write_data(
    data=data,
    table_version_id=None,
    use_deployed_version=False
)

Parameters:

• data (list[dict] | dict): Data to write (single record or list)
• override (bool, optional): Whether to override existing data. Default: False
• table_version_id (str, optional): Write to a specific version of this table
• use_deployed_version (bool, optional): Write to the deployed version. Default: False

Returns: dict with write operation result

If you don’t specify a table_version_id and use_deployed_version is False, operations will target the latest version of the table.

Write Options

# Write single record
table.write_data({"id": "4", "name": "Alice Brown", "email": "[e-mail]"})

# Override existing data
table.write_data(new_data, override=True)

Using override=True will replace existing data in the table. Use with caution.

Read Data

Retrieve data from a table:

# Get all data (automatically paginated)
all_data = table.get_data()

# Get data with parameters
limited_data = table.get_data(
    offset=0,
    max_results=100,
    remove_embeddings=True,
    table_version_id=None,
    use_deployed_version=False,
    object_id="6f05f0b1-5cc4-47be-935e-31392d73bcf6"
)

Parameters:

• offset (int, optional): Records to skip. Default: 0
• page_size (int, optional): Records to return per page. Default: 100
• max_results (int, optional): Max records to return. Default: 10000
• remove_embeddings (bool, optional): Exclude embeddings from results. Default: True
• chunk_id (str, optional): Filter by chunk ID
• document_id (str, optional): Filter by document ID
• table_version_id (str, optional): Retrieve a specific version of this table
• use_deployed_version (bool, optional): Retrieve the deployed version. Default: False
• object_id (str, optional): Filter by object ID

Returns: list[dict] of table records

If you don’t specify a table_version_id and use_deployed_version is False, operations will target the latest version of the table.

Advanced Filters

You can use advanced filters to retrieve data from multiple documents:

# Get data from multiple documents
table.get_data(
    document_id__in=[
        "6f05f0b1-5cc4-47be-935e-31392d73bcf6",
        "950f0858-c1ed-471b-a19f-1694c7e03e27"
    ]
)

This returns all data from documents with the specified IDs.

Push to Retrieval

Make table data available for search operations by pushing it to the retrieval system:

warehouse = client.get_warehouse("warehouse-id")
table = warehouse.get_table("my-table")

result = table.push_to_retrieval()
print(f"Push result: {result}")

Parameters: None

Returns: dict with push operation result

This operation makes your table data searchable through the warehouse’s search and retrieval capabilities.

Common Usage Patterns

Write and Read Workflow

# Get warehouse and table
warehouse = client.get_warehouse("warehouse-id")
table = warehouse.get_table("my-table")

# Write data
data = [
    {"id": "1", "content": "Sample content", "metadata": {"type": "example"}},
    {"id": "2", "content": "More content", "metadata": {"type": "test"}}
]
table.write_data(data)

# Read back the data
retrieved_data = table.get_data(max_results=10)
print(f"Retrieved {len(retrieved_data)} records")

Filter by Document

# Get data for a specific document
document_data = table.get_data(
    document_id="6f05f0b1-5cc4-47be-935e-31392d73bcf6",
    remove_embeddings=True
)

Working with Versions

# Write to deployed version
table.write_data(data, use_deployed_version=True)

# Read from specific version
version_data = table.get_data(
    table_version_id="version-uuid-123",
    max_results=50
)

Pagination

# Read data in pages
page_size = 100
offset = 0
all_records = []

while True:
    page_data = table.get_data(
        offset=offset,
        page_size=page_size,
        max_results=page_size
    )

    if not page_data:
        break

    all_records.extend(page_data)
    offset += page_size

    if len(page_data) < page_size:
        break

print(f"Total records: {len(all_records)}")