Skip to content

Graph-Native Infrastructure for Context and Accountable AI Systems

3.8 KB
Raw Blame

title: "Apache Cassandra Integration" description: "Ingest structured data from Apache Cassandra tables into Semantica's KG pipeline." icon: "database"

Extract data from Apache Cassandra tables into Semantica using the official cassandra-driver.

Installation

# Install with Cassandra support
pip install "semantica[db-cassandra]"

# Or install the connector separately
pip install "cassandra-driver>=3.29.0"

cassandra-driver is an optional dependency. A plain pip install semantica does not install it, and the Cassandra connector is loaded lazily when first used.

Basic Usage

import os
from semantica.ingest import CassandraIngestor

ingestor = CassandraIngestor(
    hosts=os.getenv("CASSANDRA_HOSTS", "127.0.0.1").split(","),
    port=int(os.getenv("CASSANDRA_PORT", "9042")),
    username=os.getenv("CASSANDRA_USERNAME"),
    password=os.getenv("CASSANDRA_PASSWORD"),
    keyspace=os.getenv("CASSANDRA_KEYSPACE"),
)

data = ingestor.ingest_table("users")

print(f"Retrieved {data.row_count} rows")
print(f"Columns: {data.columns}")
Use environment variables to keep Cassandra credentials out of source code.

Authentication

For authenticated Cassandra clusters:

from semantica.ingest import CassandraIngestor

ingestor = CassandraIngestor(
    hosts=["127.0.0.1"],
    port=9042,
    username="cassandra",
    password="your-password",
    keyspace="my_keyspace",
)

For clusters without authentication:

from semantica.ingest import CassandraIngestor

ingestor = CassandraIngestor(
    hosts=["127.0.0.1"],
    port=9042,
    keyspace="my_keyspace",
)

Querying

Ingest a table

data = ingestor.ingest_table("orders")
print(f"{data.row_count} rows, columns: {data.columns}")

Limit the number of rows

data = ingestor.ingest_table(
    "orders",
    limit=1000,
)

limit is translated into a CQL LIMIT clause.

Schema Discovery

schema = ingestor.get_table_schema("users")

for column in schema["columns"]:
    print(
        f"{column['name']}: "
        f"{column['type']} "
        f"(nullable={column['nullable']})"
    )

print("Primary keys:", schema["primary_keys"])

Each column contains:

Key Type Description
name str Column name
type str Cassandra CQL type
nullable bool Whether the column is nullable
primary_key bool Whether the column is part of the primary key
static bool Whether the column is static

primary_keys contains the table's primary-key column names in Cassandra order.

Export as Semantica Documents

documents = ingestor.export_as_documents(
    data,
    id_field="id",
    text_fields=["name", "city"],
)

print(f"Created {len(documents)} documents")

Each document contains:

{
    "id": "123",
    "text": "Alice Delhi",
    "metadata": {
        "source": "cassandra",
        "keyspace": "my_keyspace",
        "table": "users",
        "row_data": {}
    }
}

ID resolution: the configured id_field is converted to a string. When the field is absent, the row index is used as a deterministic fallback.

Text when text_fields is provided: non-None values are converted to strings and joined with a single space.

Text when text_fields=None: only string values are included in the document text.

Connection Test

from semantica.ingest import CassandraConnector

connector = CassandraConnector(
    hosts=["127.0.0.1"],
    port=9042,
    keyspace="my_keyspace",
)

if connector.test_connection():
    print("Connection OK")
else:
    print("Connection failed")

See Also