Airport

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.