# Query object storage

Altertable can query data that already lives in Amazon S3, Cloudflare R2, Google Cloud Storage, or another S3-compatible bucket. Map the files once, then use the same SQL engine and query interfaces you use for Altertable catalogs.

Object storage queries run in place. Altertable reads mapped files from the connected bucket.

## Goal

Map an object-storage dataset, query it with a fully qualified table name, and join it with another Altertable catalog.

## Prerequisites

- An S3-compatible bucket containing Parquet, CSV, JSON, Iceberg, or S3 Tables data.
- Permission for Altertable to read the intended bucket paths and metadata.
- A mapped external catalog, or the connection details needed to create one.

## Steps

### 1. Choose a table type

| Source                      | Best fit                                         | Learn more                                                            |
| --------------------------- | ------------------------------------------------ | --------------------------------------------------------------------- |
| Parquet, CSV, or JSON files | Query file paths and prefixes as external tables | [Bucket Tables](/docs/lakehouse/external-catalogs/bucket-tables.md)   |
| Apache Iceberg datasets     | Query datasets through Iceberg table metadata    | [Iceberg Tables](/docs/lakehouse/external-catalogs/iceberg-tables.md) |
| Amazon S3 table buckets     | Query AWS-managed Iceberg table buckets          | [S3 Tables](/docs/lakehouse/external-catalogs/s3-tables.md)           |

Follow the guide for the selected source to map its files or metadata as a table.

### 2. Query a mapped table

After you map object storage, query the exposed tables with fully qualified names:

```sql
SELECT
  event_name,
  count(*) AS event_count
FROM bucket_exports.main.events
WHERE event_date >= DATE '2026-01-01'
GROUP BY event_name
ORDER BY event_count DESC;
```

### 3. Join another catalog

Mapped object-storage tables can be joined with Altertable-managed catalogs and other external catalogs:

```sql
SELECT
  customers.segment,
  count(*) AS events
FROM bucket_exports.main.events
JOIN analytics.main.customers
  ON events.customer_id = customers.customer_id
GROUP BY customers.segment;
```

### 4. Choose a query interface

Use object-storage tables from:

- [SQL explorer](/docs/query-data/sql-explorer.md) for interactive analysis.
- [HTTP API](/docs/query-data/http-api.md) for applications and services.
- [DuckDB](/docs/query-data/duckdb.md) for local analysis and file joins.
- [Postgres adapter](/docs/query-data/adapters/postgres.md) and [Arrow Flight SQL adapter](/docs/query-data/adapters/arrow-flight-sql.md) for BI tools.
- [MCP tools](/docs/query-data/mcp.md) and [Ask Agent](/docs/query-data/ask-agent.md) for agentic exploration.

### 5. Improve query performance

> **Recommendation: use columnar formats:**
>
> For large object-storage datasets, prefer columnar formats such as Parquet or Iceberg, keep partitions predictable, and filter on partition columns when possible. Altertable can query CSV and JSON files, but columnar formats usually scan less data and return results faster.

## Verification

Run a small count against the mapped table:

```sql
SELECT count(*) AS row_count
FROM bucket_exports.main.events;
```

Confirm that `row_count` is consistent with the files or Iceberg dataset mapped to the table.

## Troubleshooting

- **The table is not found:** qualify it with the mapped catalog and schema, then confirm the exposed table name.
- **Files are missing:** check that the mapped path or prefix includes the expected objects.
- **The bucket cannot be read:** verify the object-storage credentials and permissions for the mapped paths and metadata.
- **Queries scan too much data:** prefer Parquet or Iceberg, keep partitions predictable, and filter on partition columns.
- **A join returns no rows:** inspect the join-key types and values in each catalog before joining them.

**Continue in Altertable:** [Create catalog](/app)

## Next steps

- [Map bucket tables](/docs/lakehouse/external-catalogs/bucket-tables.md)
- [Map Iceberg tables](/docs/lakehouse/external-catalogs/iceberg-tables.md)
- [Map Amazon S3 Tables](/docs/lakehouse/external-catalogs/s3-tables.md)
- [Query with SQL Explorer](/docs/query-data/sql-explorer.md)