> ## 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.

# kumoai.connector

> Connector and SourceTable interfaces for accessing raw data

The `kumoai.connector` module provides interfaces for connecting Kumo to backing data sources and inspecting raw table data. `SourceTable` objects returned by connectors are used to create [`Table`](/sdk/kumoai-graph#table) and [`Graph`](/sdk/kumoai-graph#graph) objects for downstream ML.

***

## Uploading Your Own Data

Kumo supports uploading local tables directly. Files larger than 1 GB are supported via automatic partitioning. Tables must be a single Parquet or CSV file on your local machine. Use `FileUploadConnector.upload()` to upload and `FileUploadConnector.delete()` to remove a table.

### `FileUploadConnector`

A connector for uploading local files to the Kumo data plane.

#### `upload()`

Uploads a Parquet or CSV file to Kumo.

<ParamField body="name" type="str" required>
  The name to assign to the uploaded table.
</ParamField>

<ParamField body="path" type="str" required>
  Local path to the Parquet or CSV file.
</ParamField>

<ParamField body="auto_partition" type="bool" default="True">
  Whether to automatically partition files larger than `partition_size_mb`.
</ParamField>

<ParamField body="partition_size_mb" type="int" default="250">
  Target partition size in megabytes when `auto_partition` is enabled.
</ParamField>

**Returns** `None` (after uploading, access the table via `connector.table(name)`)

#### `delete()`

Deletes a previously uploaded table.

<ParamField body="name" type="str" required>
  The name of the uploaded table to delete.
</ParamField>

#### `source_type` `property`

**Returns** `DataSourceType` — The source type for this connector.

#### `name` `property`

**Returns** `str` — The connector name.

***

## Connector

Connectors link Kumo to data stored in an external data warehouse or object store. The SDK supports Amazon S3, Google Cloud Storage (GCS), Azure Data Lake Storage (ADLS), AWS Glue, Snowflake, BigQuery, and Databricks.

All connectors inherit the following methods from the base `Connector` class:

#### `table_names()`

**Returns** `List[str]` — Names of all tables accessible through this connector.

#### `has_table()`

<ParamField body="name" type="str" required>
  The table name to check.
</ParamField>

**Returns** `bool` — `True` if the table exists in the connector.

#### `table()`

Returns a `SourceTable` for the named table. Use the returned object to inspect raw data or construct a [`Table`](/sdk/kumoai-graph#table).

<ParamField body="name" type="str" required>
  The table name.
</ParamField>

**Returns** `SourceTable`

**Raises** `ValueError` if `name` does not exist in the connector.

***

### `SnowflakeConnector`

Connects Kumo to a Snowflake data warehouse.

#### `get_by_name()` `classmethod`

Retrieves a `SnowflakeConnector` by its registered name.

<ParamField body="name" type="str" required>
  The registered connector name.
</ParamField>

**Returns** `SnowflakeConnector`

#### `source_type` `property`

**Returns** `DataSourceType`

#### `name` `property`

**Returns** `str`

***

### `BigQueryConnector`

Connects Kumo to a Google BigQuery data warehouse.

#### `get_by_name()` `classmethod`

<ParamField body="name" type="str" required>
  The registered connector name.
</ParamField>

**Returns** `BigQueryConnector`

#### `source_type` `property`

**Returns** `DataSourceType`

#### `name` `property`

**Returns** `str`

***

### `DatabricksConnector`

Connects Kumo to a Databricks data lakehouse.

#### `get_by_name()` `classmethod`

<ParamField body="name" type="str" required>
  The registered connector name.
</ParamField>

**Returns** `DatabricksConnector`

#### `source_type` `property`

**Returns** `DataSourceType`

#### `name` `property`

**Returns** `str`

***

### `S3Connector`

Connects Kumo to an Amazon S3 object store.

#### `source_type` `property`

**Returns** `DataSourceType`

***

### `GCSConnector`

Connects Kumo to a Google Cloud Storage (GCS) bucket.

#### `get_by_name()` `classmethod`

Retrieves a `GCSConnector` by its registered name.

<ParamField body="name" type="str" required>
  The registered connector name.
</ParamField>

**Returns** `GCSConnector`

#### `source_type` `property`

**Returns** `DataSourceType`

#### `name` `property`

**Returns** `str`

***

### `ADLSConnector`

Connects Kumo to an Azure Data Lake Storage (ADLS) container.

#### `get_by_name()` `classmethod`

Retrieves an `ADLSConnector` by its registered name.

<ParamField body="name" type="str" required>
  The registered connector name.
</ParamField>

**Returns** `ADLSConnector`

#### `source_type` `property`

**Returns** `DataSourceType`

#### `name` `property`

**Returns** `str`

***

### `GlueConnector`

Connects Kumo to an AWS Glue catalog. Supports tables in partitioned Parquet format, authenticated via IAM permissions on the Glue catalog and its underlying S3 data location.

#### `get_by_name()` `classmethod`

Retrieves a `GlueConnector` by its registered name.

<ParamField body="name" type="str" required>
  The registered connector name.
</ParamField>

**Returns** `GlueConnector`

#### `source_type` `property`

**Returns** `DataSourceType`

#### `name` `property`

**Returns** `str`

***

## Source Data

Tables accessed from connectors are represented as `SourceTable` objects, with column metadata represented as `SourceColumn` objects.

### `SourceTable`

A reference to a table stored behind a backing `Connector`. Use it to inspect raw data before constructing a [`Table`](/sdk/kumoai-graph#table) for ML.

```python theme={null}
connector = kumoai.SnowflakeConnector.get_by_name("my-connector")
src = connector.table("orders")
src.head(10)
```

<ParamField body="name" type="str" required>
  The name of the table in the backing connector.
</ParamField>

<ParamField body="connector" type="Connector" required>
  The connector containing this table.
</ParamField>

#### `columns` `property`

**Returns** `List[SourceColumn]` — Column metadata for all columns in this table.

#### `column_dict` `property`

**Returns** `Dict[str, SourceColumn]` — Column metadata keyed by column name.

#### `head()`

Returns the first `num_rows` rows by reading from the backing connector.

<ParamField body="num_rows" type="int" default="5">
  Number of rows to return. Returns all rows if fewer are available.
</ParamField>

**Returns** `pd.DataFrame`

#### `add_llm()`

Enriches the table with LLM-generated embeddings, adding a new embedding column.

<ParamField body="model" type="str" required>
  The embedding model name (e.g. `"text-embedding-3-small"`).
</ParamField>

<ParamField body="api_key" type="str" required>
  API key for the embedding model provider.
</ParamField>

<ParamField body="template" type="str" required>
  A template string defining which columns to embed (e.g. `"{title} {description}"`).
</ParamField>

<ParamField body="output_dir" type="str" required>
  Output directory path (S3 or local) where the enriched table is written.
</ParamField>

<ParamField body="output_column_name" type="str" required>
  Name of the new embedding column in the output table.
</ParamField>

<ParamField body="output_table_name" type="str" required>
  Name of the output table.
</ParamField>

<ParamField body="dimensions" type="int" default="None">
  Embedding dimensionality. Uses the model's default if not specified.
</ParamField>

<ParamField body="non_blocking" type="bool" default="False">
  If `True`, returns an `LLMSourceTableFuture` immediately rather than blocking.
</ParamField>

**Returns** `Union[SourceTable, LLMSourceTableFuture]`

***

### `SourceTableFuture`

Represents an ongoing asynchronous `SourceTable` generation process.

#### `result()`

Blocks until complete and returns the `SourceTable`.

**Returns** `SourceTable`

#### `status()`

**Returns** `JobStatus` — Current status of the job.

#### `future()`

**Returns** `concurrent.futures.Future[SourceTable]` — The underlying future object.

***

### `LLMSourceTableFuture`

Extends `SourceTableFuture` with cancellation support for LLM enrichment jobs.

#### `cancel()`

Cancels the running LLM enrichment job.

**Returns** `JobStatus`

***

### `SourceColumn`

Metadata for a single column in a `SourceTable`, including its name and inferred data type.