Airport

What Airport gets you

If you operate a service that already speaks Arrow Flight — a custom Python or Go data API, an internal federation gateway, or a Flight-native system like Dremio or InfluxDB 3 — Airport makes it queryable from DuckDB with a single ATTACH:

CREATE OR REPLACE SECRET my_service (
  TYPE airport,
  scope 'grpc+tls://flight.example.com:8815',
  auth_token :token
);

ATTACH 'grpc+tls://flight.example.com:8815' AS svc (TYPE airport);

SELECT user_id, COUNT(*) AS events
FROM svc.public.activity
WHERE ts >= CURRENT_DATE - 7
GROUP BY user_id;

No client library, no DataFrame round-trip, no separate query API on top of your service. Just SQL.

What can I connect to?

The honest answer: any service that implements Arrow Flight. In practice that’s a narrower list than “data systems that use Arrow internally.”

Confirmed Flight-speaking systems:

• Custom services built with pyarrow.flight.FlightServerBase, the Arrow Java Flight library, or the Arrow Go Flight package. This is where Airport’s value is unambiguous — you write a 30–50 line Flight server, point Airport at it, and your service is queryable from SQL with zero client SDK on the consumer side.
• Dremio — exposes Flight SQL natively.
• InfluxDB 3 — documented Flight endpoint for query.

Not Arrow Flight, even if they use Arrow internally:

Snowflake, Microsoft Fabric, BigQuery, and several other warehouses use Arrow as their result-format wire encoding but don’t expose a public Flight server you can ATTACH to. Airport won’t help you here. For database-style remote query against systems with ADBC drivers, see the sibling adbc_scanner extension.

Who Airport is for

The most underrated angle: platform and data engineering teams who already run an internal data service. If your service produces tabular data and you’re considering inventing a SQL query API on top of it (translating predicates, paginating, handling joins), don’t. Implement pyarrow.flight.FlightServerBase — a few dozen lines — and your service inherits SQL access for free via Airport. DuckDB becomes the query engine; you just write the data-fetch path.

The other natural fit is federation: DuckDB joining across multiple Flight backends (your custom service, a Dremio instance, an InfluxDB measurement) in one query, without an orchestration layer.

How it integrates with DuckDB

• ATTACH ... (TYPE airport) — full catalog integration. Schema discovery, joins across local and remote tables, query pushdown where the server supports it, and INSERT / UPDATE / DELETE to writable backends.
• Table functions — airport_flights, airport_take_flight, airport_action, airport_databases for ad-hoc / streaming use without ATTACH.
• Secret type airport — managed credentials (location, auth_token, criteria) passed by name to all of the above. See CREATE SECRET and the DuckDB Secrets Manager.

Airport vs ADBC Scanner

Both extensions stream Arrow from a remote system end-to-end, but they target different worlds — pick by what’s on the other end of the wire:

• Use Airport when the upstream speaks Arrow Flight — typically custom services, Flight-native systems, or federation gateways. Flight is an RPC protocol.
• Use adbc_scanner when the upstream is a database with an ADBC driver — SQLite, PostgreSQL, Snowflake, BigQuery, etc. ADBC is a client API standard, not a wire protocol.
• Both can coexist in the same DuckDB session: Airport for Flight-native services, adbc_scanner for traditional databases, all queryable side by side.

Background: what is Arrow Flight?

Arrow Flight is the Apache Arrow project’s wire protocol for moving Arrow data over the network. It runs on gRPC over HTTP/2 and uses Arrow’s columnar IPC format end-to-end, so result batches arrive on the client in the same layout the server produced them — no row/column transposition. The protocol’s standard verb vocabulary — ListFlights, GetFlightInfo, DoGet, DoPut, DoExchange, DoAction — is what Airport translates DuckDB SQL into. The full design rationale for Airport and server implementation guides live at airport.query.farm.

Try it against the live demo server

Query.Farm runs a public demo Flight server at grpc+tls://hello-airport.query.farm so you can exercise Airport without building anything. Attach it, switch to the static schema, and join across two of its tables:

-- Connect to a remote Arrow Flight server
ATTACH 'hello' (TYPE AIRPORT, location 'grpc+tls://hello-airport.query.farm');

-- Switch to the static schema
USE hello.static;

-- Query remote tables with standard SQL — notice the join across two remote tables
SELECT greeting || ', ' || first_name || ' welcome to Airport.' AS greeting
FROM greetings
JOIN people ON people.language = greetings.language
LIMIT 3;

The chat schema demonstrates writes against a Flight server too — auto-assigned identity, message inserts, and a recent-messages query in the same session:

-- Switch to the chat schema
USE hello.chat;

-- Get your auto-generated identity
SELECT * FROM identity;

-- Post a message to the 'airport' channel
INSERT INTO messages (channel, message)
VALUES ('airport', 'Hello from Airport!');

-- See all recent messages
SELECT sender, message, timestamp
FROM messages
WHERE channel = 'airport'
ORDER BY timestamp DESC
LIMIT 10;

See airport.query.farm for the demo’s full schema reference and notes on the underlying Flight server implementation.

Attach a Flight Database

The most powerful way to use Airport: attach an Arrow Flight server as a DuckDB database via ATTACH and query it like any other catalog.

-- 1. Store credentials with CREATE SECRET. `scope` is the Flight URL
--    the secret applies to — DuckDB matches the secret by URL prefix.
CREATE OR REPLACE SECRET my_flight (
  TYPE airport,
  scope 'grpc+tls://flight.example.com:8815',
  auth_token 'your-bearer-token'
);

-- 2. ATTACH the URL directly. The Secrets Manager picks up `my_flight`
--    automatically because the URL matches its scope.
ATTACH 'grpc+tls://flight.example.com:8815' AS remote (TYPE airport);

-- 3. Query as if it's local — joins, filters, aggregates all push down
--    to the Flight server when supported.
SELECT user_id, COUNT(*) AS events
FROM remote.public.activity
WHERE ts >= CURRENT_DATE - 7
GROUP BY user_id
ORDER BY events DESC
LIMIT 50;

DuckDB’s full SQL surface works against remote tables — joins across local and remote catalogs, CTEs, window functions, materialized CTAS into local tables. Credentials live in the DuckDB Secrets Manager (see CREATE SECRET) so they’re never inlined into queries — the secret is matched against the ATTACH URL by its scope prefix.

Discover What a Server Offers

Before attaching, list the databases and flights a server exposes:

-- Show databases the server hosts. `airport_databases` takes the
-- Flight URL — the same URL you'd pass to ATTACH.
SELECT * FROM airport_databases('grpc+tls://flight.example.com:8815');

-- Show all flights (schemas + metadata) under a server URL
SELECT * FROM airport_flights('grpc+tls://flight.example.com:8815');

-- Filter by descriptor pattern
SELECT * FROM airport_flights(
  'grpc+tls://flight.example.com:8815',
  /* criteria = */ 'tenant=acme'
);

The result is a table — pipe it into WHERE / LIMIT / joins to drill down without attaching. See airport_databases and airport_flights for the full signatures.

Stream a Specific Flight Inline

When you already have a flight descriptor and just want its rows once, skip ATTACH and call airport_take_flight directly:

SELECT *
FROM airport_take_flight(
  'grpc+tls://flight.example.com:8815',
  /* descriptor = */ '{"path":["sales","2026-04"]}'
)
LIMIT 100;

Useful for read-once jobs, exports, or wiring Flight responses into a CTAS.

Invoke a Server Action

Arrow Flight has a separate RPC channel called Actions for non-query operations — refreshing a materialized view, taking a snapshot, calling a stored procedure. Airport exposes them via airport_action:

-- Trigger a server-defined "refresh" action and capture the result body
SELECT *
FROM airport_action(
  'grpc+tls://flight.example.com:8815',
  /* action = */ 'refresh',
  /* body = */ '{"tenant":"acme","since":"2026-04-01"}'
);

The full set of available actions is server-defined — see your Flight server’s documentation for the action vocabulary.

Mutate a Remote Table

Airport supports INSERT / UPDATE / DELETE against attached Flight databases when the server implements the corresponding writer endpoints (Flight’s DoPut):

INSERT INTO remote.public.events
SELECT user_id, event_type, ts
FROM staging.new_events;

UPDATE remote.public.profile
SET country = 'CA'
WHERE user_id = 12345;

Whether each operation is supported depends on the server — airport_databases typically reports per-database write capabilities.

Diagnostics

SELECT airport_version();        -- e.g. '0.4.2'

SELECT airport_user_agent();     -- the User-Agent string Airport sends

Use airport_version and airport_user_agent to confirm what’s loaded and to match Flight server logs against a specific extension build when debugging.