> ## Documentation Index
> Fetch the complete documentation index at: https://kumo.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Connector Reference

> Reference for Kumo SDK connector classes and table access patterns

The Kumo SDK exposes connector classes for object storage, warehouses, uploaded files, AWS Glue, and administrator-managed group connectors. Use a connector to obtain `SourceTable` objects, then convert those source tables into Kumo `Table` objects for your graph.

```python theme={null}
import kumoai as kumo

kumo.init(url="https://<customer_id>.kumoai.cloud/api", api_key="<api_key>")

connector = kumo.S3Connector(root_dir="s3://my-bucket/kumo-input/")
orders_src = connector["orders"]        # same as connector.table("orders")
print(connector.table_names())
print(orders_src.head())
```

## Connector classes

| Connector             | Use for                                              | Required setup                                                                                |
| --------------------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| `S3Connector`         | CSV or Parquet files in Amazon S3                    | Kumo deployment role can read the bucket/prefix                                               |
| `GCSConnector`        | CSV or Parquet files in Google Cloud Storage         | Kumo workload identity can read the bucket/prefix                                             |
| `ADLSConnector`       | CSV or Parquet files in Azure Data Lake Storage      | Kumo workload identity can read `abfs://` or `abfss://` paths                                 |
| `SnowflakeConnector`  | Tables and views in a Snowflake schema               | Snowflake account, warehouse, database, schema, and credentials unless using native SPCS auth |
| `DatabricksConnector` | Tables in a Databricks catalog                       | Databricks host plus warehouse/cluster/catalog and OAuth or PAT credentials                   |
| `BigQueryConnector`   | Tables in a BigQuery dataset                         | Project, dataset, and service-account credentials                                             |
| `GlueConnector`       | Partitioned Parquet tables in AWS Glue Catalog       | Glue catalog metadata and IAM access to the backing S3 data                                   |
| `FileUploadConnector` | Local or remote CSV/Parquet files uploaded into Kumo | Use `upload()` before reading the table                                                       |
| `GroupConnector`      | Admin-managed connectors in RBAC-enabled workspaces  | Select a group, then call `kumo.list_group_connectors()`                                      |

<Note>
  If you use Kumo in Snowpark Container Services, `SnowflakeConnector` is the supported connector type.
</Note>

## Object storage connectors

Object storage connectors share the same access pattern. Create the connector with a root directory and read tables by relative table name. If you omit `root_dir`, pass the full table path to `table()`.

```python theme={null}
s3 = kumo.S3Connector(root_dir="s3://my-bucket/kumo/")
gcs = kumo.GCSConnector(root_dir="gs://my-bucket/kumo/")
adls = kumo.ADLSConnector(root_dir="abfss://container@account.dfs.core.windows.net/kumo/")

orders = s3.table("orders")
customers = gcs["customers"]
transactions = adls.table("transactions")

# Full-path access is also supported when no root_dir is configured.
events = kumo.S3Connector().table("s3://my-bucket/other/events/")
```

## Warehouse connectors

Warehouse connectors create or attach to named Kumo connector resources. You can supply credentials directly or set the documented environment variables before constructing the connector.

### Snowflake

```python theme={null}
snowflake = kumo.SnowflakeConnector(
    name="prod_snowflake",
    account="<account>",
    warehouse="COMPUTE_WH",
    database="ANALYTICS",
    schema_name="PUBLIC",
    credentials={"user": "<user>", "password": "<password>"},
)

orders = snowflake.table("ORDERS")
```

`SnowflakeConnector` can also use `SNOWFLAKE_USER`, `SNOWFLAKE_PASSWORD`, `SNOWFLAKE_PRIVATE_KEY`, and `SNOWFLAKE_PRIVATE_KEY_PASSPHRASE` environment variables. In SPCS environments initialized with `snowflake_credentials`, those credentials are reused when connector credentials are omitted; when initialized from a Snowflake notebook with `snowflake_application`, the SDK can create a native Snowflake connector without explicit connector credentials.

### Databricks

```python theme={null}
databricks = kumo.DatabricksConnector(
    name="prod_databricks",
    host="https://<workspace>.cloud.databricks.com",
    cluster_id="<cluster_id>",
    warehouse_id="<warehouse_id>",
    catalog="main",
    credentials={"token": "<personal_access_token>"},
)

orders = databricks.table("sales.orders")
```

Use either a personal access token (`token` or `DATABRICKS_TOKEN`) or OAuth client credentials (`client_id`/`client_secret` or `DATABRICKS_CLIENT_ID`/`DATABRICKS_CLIENT_SECRET`), not both.

### BigQuery

```python theme={null}
bigquery = kumo.BigQueryConnector(
    name="prod_bigquery",
    project_id="my-gcp-project",
    dataset_id="analytics",
    credentials={
        "private_key_id": "<private_key_id>",
        "private_key": "<private_key>",
        "client_id": "<client_id>",
        "client_email": "<client_email>",
        "token_uri": "https://oauth2.googleapis.com/token",
        "auth_uri": "https://accounts.google.com/o/oauth2/auth",
    },
)

orders = bigquery.table("orders")
```

Equivalent environment variables are `BIGQUERY_PRIVATE_KEY_ID`, `BIGQUERY_PRIVATE_KEY`, `BIGQUERY_CLIENT_ID`, `BIGQUERY_CLIENT_EMAIL`, `BIGQUERY_TOKEN_URI`, and `BIGQUERY_AUTH_URI`.

### AWS Glue

```python theme={null}
glue = kumo.GlueConnector(
    name="prod_glue",
    account="123456789012",
    region="us-west-2",
    database="analytics",
)

orders = glue.table("orders")
```

`GlueConnector` currently targets partitioned Parquet tables registered in the Glue Catalog.

## Reusing existing connectors

For connectors that are stored in Kumo, retrieve a connector created earlier or created in the UI with `get_by_name()`.

```python theme={null}
snowflake = kumo.SnowflakeConnector.get_by_name("prod_snowflake")
databricks = kumo.DatabricksConnector.get_by_name("prod_databricks")
bigquery = kumo.BigQueryConnector.get_by_name("prod_bigquery")
glue = kumo.GlueConnector.get_by_name("prod_glue")
```

## Uploaded files

Use `FileUploadConnector` when you have a local file or a remote file/directory that should be uploaded into Kumo-managed storage before it is used as a source table.

```python theme={null}
parquet_uploads = kumo.FileUploadConnector(file_type="parquet")
parquet_uploads.upload(name="customers", path="/data/customers.parquet")

csv_uploads = kumo.FileUploadConnector(file_type="csv")
csv_uploads.upload(name="events", path="gs://my-bucket/staging/events_csv/")

customers = parquet_uploads["customers"]
events = csv_uploads.table("events")
```

Local files larger than about 1 GB are automatically partitioned by default. Remote single files must be about 1 GB or smaller; for larger remote data, upload a directory of same-format shards.

## Group connectors

In RBAC-enabled workspaces, administrators can expose shared connectors at the group level. Users list and select those connectors instead of creating connectors with raw credentials.

```python theme={null}
kumo.init(
    url="https://<customer_id>.kumoai.cloud/api",
    api_key="<api_key>",
    group="marketing",
    project="churn-modeling",
)

for connector in kumo.list_group_connectors():
    print(connector.display_name, connector.source_type, connector.scope)

connector = kumo.list_group_connectors()[0]
orders = connector.table("sales.orders")
```

If your workspace uses project scoping, initialize the SDK with the appropriate `group` and `project` before listing group connectors.

## After selecting source tables

After a connector returns `SourceTable` objects, continue with table and graph construction:

```python theme={null}
orders = kumo.Table.from_source_table(
    source_table=orders_src,
    time_column="created_at",
).infer_metadata()

customers = kumo.Table.from_source_table(
    source_table=customers_src,
    primary_key="customer_id",
).infer_metadata()
```

Next, see [Tables](/fine-tuning/tables) and [Graphs](/fine-tuning/graphs).