Skip to content
DocumentationQuery data
Query data
Object Storage

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
Apache Iceberg datasets
Query datasets through Iceberg table metadata
Iceberg Tables
Amazon S3 table buckets
Query AWS-managed Iceberg table buckets
S3 Tables

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:

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:

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:

5. Improve query performance

Verification

Run a small count against the mapped table:

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.

Next steps