Amazon S3

Use the Amazon S3 connector to load CSV files, Parquet files, or Parquet datasets from S3 into pandas DataFrames. Pass these DataFrames to relational.Graph.from_data() to build a Kumo relational graph, which describes the tables and relationships used for prediction.

Unlike the SQL connectors, S3 does not provide a schema catalog or a Graph.from_s3() constructor. You must read each object explicitly.

Before you begin, make sure your runtime can access the S3 bucket that contains your data.

Installation

Install the Kumo relational client with support for graph construction and S3:

pip install "kumo-relational-client[relational,s3]"

Read an object

Call read() with the s3 connector and an S3 URI. The function returns a pandas DataFrame:

from kumo_relational_client import read
orders = read(
    "s3",
    path="s3://my-bucket/warehouse/orders.parquet",
)

The connector determines the data format from the path suffix and supports:

• CSV files with .csv or .txt suffixes, optionally compressed.
• Parquet files with .parquet, .pq, or .parq suffixes.
• Directories containing a Parquet dataset.

For an object without a recognized suffix, pass format="csv" or format="parquet" explicitly.

Configure storage access

Pass authentication and filesystem options to pandas through storage_options:

orders = read(
    "s3",
    path="s3://my-bucket/warehouse/orders.parquet",
    storage_options={
        "key": "<access-key-id>",
        "secret": "<secret-access-key>",
    },
)

Do not store credentials in source code. Prefer the ambient AWS credential chain, an instance or workload role, or values loaded from your platform’s secret manager. Omit storage_options when the runtime is already configured to authenticate to S3.

Build a graph

For a graph with multiple S3-backed tables, read each table and pass the resulting DataFrames to relational.Graph.from_data():

from kumo_relational_client import read, relational
customers = read("s3", path="s3://my-bucket/customers.parquet")
orders = read("s3", path="s3://my-bucket/orders.parquet")
graph = relational.Graph.from_data(
    {
        "customers": customers,
        "orders": orders,
    }
)

Before prediction, review the metadata and relationships that Kumo inferred from the DataFrames. Loading an S3 object places the complete object in client memory. If the data is too large to load in full, use a data warehouse connector that supports sampling instead.

Troubleshooting

• MISSING_EXTRA: Install kumo-relational-client[s3] in the active environment.
• INVALID_CONNECTOR_ARGS: Confirm that path is an s3:// URI and the file has a supported suffix, or pass format explicitly.
• NOT_FOUND: Confirm the bucket, object key, region, and credentials.
• READ_FAILED: Verify the object format and the permissions granted to the active AWS identity.

See Create a Graph to configure and validate the resulting tables.