# Ingest or connect?

**Ingest data** to copy records or files into Altertable-managed tables. **Connect an external catalog** to query data where it already lives. You can use both and join their tables with SQL.

## Choose a route

| Your data                                                            | Route                                                                                                                       | Where the queried data lives             |
| -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
| Existing database or warehouse                                       | [External catalog](/docs/lakehouse/external-catalogs.md)                                                                    | In the source system                     |
| Files, Iceberg datasets, or managed table catalogs in object storage | [Query object storage](/docs/lakehouse/query/object-storage.md)                                                             | In your bucket or table catalog          |
| Local CSV, JSON, or Parquet files                                    | [Upload files](/docs/lakehouse/ingest/http-api.md#3-upload-files)                                                           | In managed lakehouse tables              |
| New files arriving in a bucket                                       | [Bucket synchronizer](/docs/lakehouse/ingest/object-storage.md)                                                             | Copied into managed tables on a schedule |
| Application records or backend events                                | [Append or upsert](/docs/lakehouse/ingest/http-api.md)                                                                      | In managed lakehouse tables              |
| DataFrames or local DuckDB results                                   | [DataFrame ingestion](/docs/lakehouse/ingest/pandas-polars-ibis.md) or [DuckDB ingestion](/docs/lakehouse/ingest/duckdb.md) | In managed lakehouse tables              |
| Product behavior and user identities                                 | [Product Analytics SDK or API](/docs/product-analytics/setup.md)                                                            | In the Product Analytics catalog         |
| Application logs and traces                                          | [OpenTelemetry SDK or collector](/docs/opentelemetry/setup.md)                                                              | In the OpenTelemetry catalog             |
| Existing data pipelines                                              | [Pipeline integration](/docs/lakehouse/ingest/integrations.md)                                                              | Depends on the integration               |

Connecting a source does not schedule a copy of its data. Query freshness and performance depend on the source. A bucket synchronizer copies new files into managed tables on its configured schedule.

## Choose the ingestion operation

- **Append** for new JSON records. Altertable can create missing tables and add columns.
- **Upload** to create a table from a file or append file rows. Use overwrite only when you intend to replace the table.
- **Upsert** to insert new rows and update matching rows by a primary key.

See the [ingestion guide](/docs/lakehouse/ingest/http-api.md) for working examples and the [HTTP API reference](/docs/api-references/lakehouse.md) for request limits and exact behavior.

## Ask your agent to choose

```text
Read https://altertable.ai/docs/lakehouse/ingest-or-connect.md. Help me choose how to bring my data to Altertable. Inspect available project and catalog context, then ask where the data lives, whether it must stay there, and how fresh it needs to be if those details are missing. Recommend a supported ingestion or external-catalog route. Explain copying, data residency, freshness, and access requirements. Stop at a concrete setup plan; do not create a connection or ingest data yet.
```