### Install and Load Airport Extension in DuckDB

Source: https://airport.query.farm/build_instructions

This SQL snippet shows how to install the Airport extension from the community repository and then load it into DuckDB. This is an alternative to building the extension from source.

```sql
INSTALL airport from community;
LOAD airport;

```

--------------------------------

### SQL Query Example for String Comparison

Source: https://airport.query.farm/server_predicate_pushdown

A standard SQL query example demonstrating a string comparison filter on the 'title' column of a database table. This query is used to illustrate how predicate pushdown works.

```sql
SELECT * FROM example_table WHERE title = 'Y Combinator';
```

--------------------------------

### Install and Load Airport Extension in DuckDB

Source: https://airport.query.farm/faq

This snippet shows how to install the Airport extension from the community repository and then load it into your DuckDB session. Ensure you have a compatible DuckDB version (1.3.0 or greater).

```sql
INSTALL airport FROM community;
LOAD airport;
```

--------------------------------

### Airport Get Catalog Version Parameters

Source: https://airport.query.farm/server_action_create_transaction

Defines the parameters required for retrieving the catalog version.

```APIDOC
## Airport Get Catalog Version Parameters

### Description
This structure defines the parameters required to get the catalog version.

### Method
GET

### Endpoint
/websites/airport_query_farm/catalog_version

### Parameters
#### Query Parameters
- **catalog_name** (string) - Required - The name of the catalog for which to retrieve the version.

### Response
#### Success Response (200)
- **version** (string) - The current version of the catalog.

#### Response Example
```json
{
  "version": "1.2.3"
}
```
```

--------------------------------

### Clone Airport Extension and Setup vcpkg for DuckDB Build

Source: https://airport.query.farm/build_instructions

This snippet clones the DuckDB Airport extension repository, including its submodules, and sets up vcpkg for managing dependencies. It exports the vcpkg toolchain path for use in makefiles and demonstrates how to use ninja with make for faster builds.

```shell
# This clones the git repository of the extension.
# duckdb and extension-ci-tools are submodules.git clone --recursive git@github.com:Query-farm/duckdb-airport-extension

# Clone the vcpkg repo
#
#   vcpkg manages all of the dependencies of the airport extention and is
#   well integrated into DuckDB.git clone https://github.com/Microsoft/vcpkg.git

# Bootstrap vcpkg
./vcpkg/bootstrap-vcpkg.sh

# Store the toolchain path for vcpkg, so it can be called
# by the makefiles.
export VCPKG_TOOLCHAIN_PATH=`pwd`/vcpkg/scripts/buildsystems/vcpkg.cmake

# If you have the ninja build tool installed,
# you can use it to speed up the build, otherwise
# just run make by itself.
GEN=ninja make

```

--------------------------------

### SQL INSERT Statement Example with Airport Extension

Source: https://airport.query.farm/table_insert

Demonstrates how to attach an Airport database and insert a single row into a table. This example assumes a running Arrow Flight server at the specified location.

```sql
ATTACH 'example' (TYPE AIRPORT, location 'grpc://localhost:50312/');

CREATE TABLE example.main.employees (
  name varchar,
  id integer
);

INSERT INTO example.main.employees values ('Rusty', 1);
```

--------------------------------

### Scalar Function Invocation Example

Source: https://airport.query.farm/scalar_functions

Demonstrates how to call a scalar function directly and with schema/database qualification.

```APIDOC
## SELECT geocode_address('1024 Lenox Ave, Miami Beach, Florida 33139')

### Description
This is an example of directly invoking a scalar function.

### Method
Not applicable (SQL Query)

### Endpoint
Not applicable (SQL Query)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```sql
SELECT geocode_address('1024 Lenox Ave, Miami Beach, Florida 33139')
```

### Response
#### Success Response (200)
Returns a single result from the scalar function.

#### Response Example
```json
{
  "result": "<function_output>"
}
```

## SELECT geocoder.usa.geocode_address('1024 Lenox Ave, Miami Beach, Florida 33139')

### Description
This example shows how to call a scalar function when the database (`geocoder`) and schema (`usa`) are explicitly provided.

### Method
Not applicable (SQL Query)

### Endpoint
Not applicable (SQL Query)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```sql
SELECT geocoder.usa.geocode_address('1024 Lenox Ave, Miami Beach, Florida 33139')
```

### Response
#### Success Response (200)
Returns a single result from the scalar function, qualified by database and schema.

#### Response Example
```json
{
  "result": "<function_output>"
}
```
```

--------------------------------

### DuckDB Airport Extension Benchmark Configuration (Conceptual)

Source: https://airport.query.farm/benchmark

This represents a conceptual setup for running benchmarks using the Airport extension in DuckDB. It outlines the typical parameters and operations tested, including scalar functions and table operations on different data types.

```python
import duckdb
import time

# Connect to DuckDB
con = duckdb.connect(database=':memory:', read_only=False)

# Assume Airport extension is loaded
# con.execute('LOAD "airport";')

# --- Scalar Function Benchmarks ---

# Echo BIGINT
start_time = time.time()
# result = con.execute("SELECT airport.echo_bigint(12345) FROM range(100000000)").fetchall()
# duration = time.time() - start_time
# print(f"Echo BIGINT: {duration:.2f}s")

# Add BIGINT
# start_time = time.time()
# result = con.execute("SELECT airport.add_bigint(10, 20) FROM range(100000000)").fetchall()
# duration = time.time() - start_time
# print(f"Add BIGINT: {duration:.2f}s")

# Echo 32-byte String
# string_val = 'a' * 32
# start_time = time.time()
# result = con.execute(f"SELECT airport.echo_string32('{string_val}') FROM range(40000000)").fetchall()
# duration = time.time() - start_time
# print(f"Echo 32-byte String: {duration:.2f}s")

# --- Remote Table Creation Benchmarks ---

# Create Remote Table from 32-byte String (Conceptual - requires data source)
# start_time = time.time()
# con.execute("CREATE TABLE remote_strings AS SELECT * FROM 'path/to/string_data.csv'") # Example
# duration = time.time() - start_time
# print(f"Create remote table (32-byte string): {duration:.2f}s")

# Create Remote Table from BIGINT (Conceptual - requires data source)
# start_time = time.time()
# con.execute("CREATE TABLE remote_bigints AS SELECT * FROM 'path/to/bigint_data.csv'") # Example
# duration = time.time() - start_time
# print(f"Create remote table (BIGINT): {duration:.2f}s")

# --- Select Queries Benchmarks ---

# Select from 32-byte String Table
# start_time = time.time()
# result = con.execute("SELECT * FROM remote_strings LIMIT 10000000").fetchall() # Example
# duration = time.time() - start_time
# print(f"Select from string table: {duration:.2f}s")

# Select from BIGINT Table
# start_time = time.time()
# result = con.execute("SELECT * FROM remote_bigints LIMIT 10000000").fetchall() # Example
# duration = time.time() - start_time
# print(f"Select from BIGINT table: {duration:.2f}s")

con.close()

```

--------------------------------

### SQL Example: Regular Table Returning Function

Source: https://airport.query.farm/table_returning_functions

Demonstrates a basic SQL query that calls a custom table returning function with a single string argument. This function is expected to return rows conforming to a dynamically defined schema.

```sql
SELECT * from custom_function('arg1');
```

--------------------------------

### Airport Extension Authentication Setup

Source: https://airport.query.farm/request_authentication

This section details how to set up authentication for the Airport extension using the DuckDB secrets manager. It covers the creation of 'airport' type secrets and their properties.

```APIDOC
## Airport Extension Authentication

### Description
This section describes how to configure authentication for the Airport extension in DuckDB. It utilizes the DuckDB secrets manager to store authentication credentials, specifically bearer tokens for Arrow Flight servers.

### Method
CREATE PERSISTENT SECRET

### Endpoint
N/A (Database command)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
N/A (Database command)

### Request Example
```sql
CREATE PERSISTENT SECRET airport_autogluon (
  type airport,
  auth_token 'example_token',
  scope 'grpc://localhost:50312/'
);
```

### Response
#### Success Response (200)
Success message indicating the secret was created.

#### Response Example
```
Secret 'airport_autogluon' created successfully.
```

### Secret Properties
- **`type`** (string) - Required - Must be 'airport' for this secret type.
- **`auth_token`** (string) - Required - The bearer token value to use for requests to the Arrow Flight server.
- **`scope`** (string) - Required - A string prefix that is matched against the destination location of the Arrow Flight server to determine which secret will be used. This is useful to use a possibly use a single secret for an entire host or domain name.
```

--------------------------------

### Create DuckDB Schema with Airport Extension

Source: https://airport.query.farm/schema_create

This example demonstrates how to attach a DuckDB database managed by the Airport extension and then create a new schema within it using standard SQL. It assumes the Airport extension is configured and accessible.

```sql
-- Attach an Airport database
ATTACH 'example' (TYPE AIRPORT, location 'grpc://localhost:50312/');

-- Create a new schema called main in the
-- example catalog
CREATE SCHEMA example.main;
```

--------------------------------

### SQL Query: Filter with AND and Length Function

Source: https://airport.query.farm/server_predicate_pushdown

This SQL query filters records from 'example_table' based on two conditions: the 'title' must start with 'R' (using LIKE) and the 'title' must have a length greater than 10 (using LENGTH). It selects all columns for matching rows.

```sql
SELECT * FROM example_table WHERE title like 'R%' AND length(title) > 10;
```

--------------------------------

### SQL Example: In-Out Table Returning Function

Source: https://airport.query.farm/table_returning_functions

Illustrates how to call an 'in-out' table returning function, which accepts both scalar parameters and the output of another query (e.g., from the 'employees' table). The results from the subquery are streamed to the function.

```sql
SELECT * from in_out_function('arg1',
 (SELECT * from employees where name ilike 'R%')
);
```

--------------------------------

### DuckDB Time Travel Query Examples

Source: https://airport.query.farm/server_time_travel

Demonstrates how to query a DuckDB table at a specific point in time using either a timestamp or a version number. This functionality allows for historical data analysis.

```sql
-- Query table as it existed at a specific timestamp
SELECT * FROM example.main.exployees AT (TIMESTAMP => TIMESTAMP '2020-01-01');

-- Query table by a specific version number
SELECT * FROM example.main.employees AT (VERSION => 42);
```

--------------------------------

### DuckDB SQL to Alter Table with Airport Extension

Source: https://airport.query.farm/table_alter

This example demonstrates how to attach an Airport database in DuckDB and execute a standard SQL ALTER TABLE statement to modify a table schema. It assumes the Airport extension is installed and a gRPC server is running at the specified location. The example shows creating a table and then dropping a column from it.

```sql
-- Attach an Airport database
ATTACH 'example' (TYPE AIRPORT, location 'grpc://localhost:50312/');

-- assume that there is a `main` schema
-- already in the `example` database
CREATE TABLE example.main.employees (
  name varchar,
  id integer
);

ALTER TABLE example.main.employees DROP COLUMN id;
```

--------------------------------

### Create Schema API

Source: https://airport.query.farm/server_action_create_schema

This API action is used to create a schema in a database. It corresponds to the `CREATE SCHEMA` SQL command.

```APIDOC
## POST /websites/airport_query_farm/create_schema

### Description
Creates a new schema in the database using the `CREATE SCHEMA` SQL command.

### Method
POST

### Endpoint
/websites/airport_query_farm/create_schema

### Parameters
#### Request Body
- **catalog_name** (string) - Required - The name of the catalog where the schema will be created.
- **schema** (string) - Required - The name of the schema to create.
- **comment** (string) - Optional - A comment describing the schema.
- **tags** (object) - Optional - A map of key-value pairs for tagging the schema.

### Request Example
```json
{
  "catalog_name": "my_catalog",
  "schema": "my_schema",
  "comment": "This is a new schema",
  "tags": {
    "environment": "production"
  }
}
```

### Response
#### Success Response (200)
- **sha256_hash** (string) - The SHA256 hash of the created schema contents.

#### Response Example
```json
{
  "sha256_hash": "a1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4e5f67890"
}
```
```

--------------------------------

### Remote Table Creation: 32-byte String Benchmark

Source: https://airport.query.farm/benchmark

Benchmarks the creation of a remote table from 32-byte string data. Performance is influenced by single-threaded serialization and data transport overhead, showing the cost associated with data ingestion into remote tables.

```sql
-- This is a conceptual representation of the SQL operation
-- Actual benchmark would involve DuckDB SQL execution
-- CREATE TABLE remote_string_table AS SELECT * FROM source_data_with_strings;
```

--------------------------------

### Create Table with Airport Extension (SQL)

Source: https://airport.query.farm/table_create

Demonstrates how to attach an Airport database and create tables using standard SQL syntax within a schema managed by the Airport extension. This allows for table creation managed by an Arrow Flight server.

```sql
-- Attach an Airport database
ATTACH 'example' (TYPE AIRPORT, location 'grpc://localhost:50312/');

-- assume that there is a `main` schema
-- already in the `example` database
CREATE TABLE example.main.employees (
  name varchar,
  id integer
);

-- You can also CREATE TABLE AS
CREATE TABLE more_employees AS (
  SELECT * from source_table
);
```

--------------------------------

### Update Table Example

Source: https://airport.query.farm/table_update

Demonstrates how to update a single row in an Airport-managed table using a standard SQL UPDATE statement.

```APIDOC
## POST /websites/airport_query_farm/update

### Description
This endpoint allows for updating rows in an Airport-managed table. An `UPDATE` statement is used, and the table must possess a `rowid` pseudocolumn for the operation to succeed. The Arrow Flight server handles the persistence of updated data.

### Method
POST

### Endpoint
/websites/airport_query_farm/update

### Parameters
#### Query Parameters
- **operation** (string) - Required - Must be set to `update` to indicate the operation type.
- **return-chunks** (integer) - Optional - Set to `1` if a `RETURNING` clause is present in the SQL statement, otherwise `0`.

#### Request Body
- **sql_statement** (string) - Required - The SQL `UPDATE` statement to be executed. Example: `UPDATE example.main.employees set id = 5 where id = 1;`

### Request Example
```json
{
  "sql_statement": "UPDATE example.main.employees set id = 5 where id = 1;"
}
```

### Response
#### Success Response (200)
- **total_changed** (uint64_t) - The total number of rows successfully updated in the table.

#### Response Example
```json
{
  "total_changed": 1
}
```

#### Error Response (Non-200)
- **error** (string) - A message describing the error encountered during the update operation. This could include issues like missing `rowid` pseudocolumn or server-side commit failures.
```

--------------------------------

### Get Airport Extension Version

Source: https://airport.query.farm/api

The airport_version function is a scalar function that returns the current version of the Airport extension. It does not require any arguments.

```sql
SELECT airport_version();
```

--------------------------------

### Schema Structure for AirportSerializedSchema (C++)

Source: https://airport.query.farm/server_action_list_schemas

Describes the `AirportSerializedSchema` structure, representing an individual schema within a catalog. It includes the schema's name, description, tags, contents, and an optional flag indicating if it's the default schema.

```cpp
struct AirportSerializedSchema
{
  // The name of the schema
  std::string name;
  // The description of the schema
  std::string description;
  // Any tags to apply to the schema.
  std::unordered_map<std::string, std::string> tags;
  // The contents of the schema itself, which can be external
  // or provided inline.
  AirportSerializedContentsWithSHA256Hash contents;
  // Should this be the default schema.
  std::optional<bool> is_default;

  MSGPACK_DEFINE_MAP(schema, description, tags, contents)
};

```

--------------------------------

### Airport Extension Table Alteration

Source: https://airport.query.farm/table_alter

This section details how to alter tables using the Airport extension, including SQL examples and explanations of the Arrow Flight RPC methods involved.

```APIDOC
## Altering Tables with the Airport Extension

### Description
The Airport extension supports altering tables. The Arrow Flight server determines whether the alteration should be applied. For a DuckDB session, standard SQL `ALTER TABLE` statements are executed within a schema managed by the Airport extension.

### Method
SQL (executed via DuckDB or similar)

### Endpoint
N/A (Local execution context)

### Parameters
N/A (SQL command parameters)

### Request Example
```sql
-- Attach an Airport database
ATTACH 'example' (TYPE AIRPORT, location 'grpc://localhost:50312/');

-- Assume that there is a `main` schema already in the `example` database
CREATE TABLE example.main.employees (
  name varchar,
  id integer
);

ALTER TABLE example.main.employees DROP COLUMN id;
```

### Response
N/A (SQL command results)

## Arrow Flight Server Implementation Notes

### Description
The Airport extension performs a `DoAction` Arrow Flight RPC. The method name for this RPC corresponds to the type of alteration being performed. Each alteration type has a specific parameter structure, and all actions are expected to return no value but raise an exception on error.

### Available Alteration Types

- `add_column`: Add a column to a table.
- `add_constraint`: Add a constraint to a field.
- `add_field`: Add a field to a structure.
- `change_column_type`: Change the type of a column.
- `drop_not_null`: Drop a NOT NULL constraint from a field.
- `remove_column`: Remove a column from a table.
- `remove_field`: Remove a field from a structure.
- `rename_column`: Rename a column.
- `rename_field`: Rename a field in a structure.
- `rename_table`: Rename a table.
- `set_default`: Set a default value for a field.
- `set_not_null`: Set a field to NOT NULL.

### Method
Arrow Flight RPC (`DoAction`)

### Endpoint
`grpc://<host>:<port>/<service>` (Specific endpoint determined by Arrow Flight client)

### Parameters
Each alteration type requires a specific parameter structure. These are passed within the `DoAction` call.

### Request Example
(Specific request body structure depends on the `DoAction` implementation and the chosen alteration type. Not detailed in the provided text.)

### Response
Success: No return value.
Error: Exception raised.
```

--------------------------------

### Get Catalog Version

Source: https://airport.query.farm/server_action_catalog_version

Retrieves the current version of the database catalog from an Arrow Flight server. This action is crucial for ensuring DuckDB uses the most up-to-date schema information.

```APIDOC
## POST /catalog_version

### Description
Retrieves the current version of the database catalog from an Arrow Flight server. This action is crucial for ensuring DuckDB uses the most up-to-date schema information.

### Method
POST

### Endpoint
/catalog_version

### Parameters
#### Query Parameters
- **catalog_name** (string) - Required - The name of the catalog to query.

#### Request Body
*There is no explicit request body for this action. The parameters are passed via msgpack serialization.*

### Request Example
```
// Example msgpack serialization for AirportGetCatalogVersionParams
// catalog_name: "main_catalog"
```

### Response
#### Success Response (200)
- **catalog_version** (uint64) - The current version of the catalog.
- **is_fixed** (boolean) - If true, DuckDB will cache this version and not query again.

#### Response Example
```json
{
  "catalog_version": 1234567890,
  "is_fixed": false
}
```
```

--------------------------------

### Define AirportCreateTableParameters Structure (C++)

Source: https://airport.query.farm/server_action_create_table

Defines the structure for input parameters required by the `create_table` action. This structure is serialized using MessagePack and includes details for catalog, schema, table names, Arrow schema, conflict resolution, and constraints.

```cpp
struct AirportCreateTableParameters
{
  string catalog_name;
  string schema_name;
  string table_name;

  // The serialized Arrow schema for the table.
  string arrow_schema;

  // This will be "error", "ignore", or "replace"
  string on_conflict;

  // The list of constraint expressions.
  vector<uint64_t> not_null_constraints;
  vector<uint64_t> unique_constraints;
  vector<string> check_constraints;

  MSGPACK_DEFINE_MAP(
    catalog_name, schema_name,
    table_name, arrow_schema,
    on_conflict, not_null_constraints,
    unique_constraints, check_constraints)
};

```

--------------------------------

### Input Parameter Structure for AirportSerializedCatalogSchemaRequest (C++)

Source: https://airport.query.farm/server_action_list_schemas

Defines the structure for the `AirportSerializedCatalogSchemaRequest`, which is a single `msgpack` serialized parameter passed to the `list_schemas` action. It contains the catalog name to be queried.

```cpp
struct AirportSerializedCatalogSchemaRequest
{
  std::string catalog_name;

  MSGPACK_DEFINE_MAP(catalog_name)
};

```

--------------------------------

### Define AirportCreateSchemaParameters Structure (C++)

Source: https://airport.query.farm/server_action_create_schema

Defines the structure for input parameters used in the create_schema action. This structure is msgpack serialized and includes catalog name, schema name, an optional comment, and a map of tags. It relies on the MSGPACK_DEFINE_MAP macro for serialization.

```cpp
struct AirportCreateSchemaParameters
{
  string catalog_name;
  string schema;

  std::optional<string> comment;
  unordered_map<string, string> tags;

  MSGPACK_DEFINE_MAP(catalog_name, schema, comment, tags)
};

```

--------------------------------

### DELETE Operation for Airport Extension

Source: https://airport.query.farm/table_delete

This section details how to perform DELETE operations on tables managed by the Airport extension. It includes SQL examples and crucial implementation notes regarding the Arrow Flight server.

```APIDOC
## DELETE FROM example.main.employees

### Description
Deletes rows from a table managed by the Airport extension. The Airport extension allows tables it manages to have rows deleted, with the Arrow Flight server responsible for performing these deletions.

### Method
SQL Statement (DELETE)

### Endpoint
N/A (SQL Operation)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A (SQL WHERE clause specifies rows to delete)

### Request Example
```sql
-- Attach an Airport database
ATTACH 'example' (TYPE AIRPORT, location 'grpc://localhost:50312/');

-- Assume that there is a `main` schema
-- already in the `example` database
CREATE TABLE example.main.employees (
  name varchar,
  id integer
);

-- Delete a single row
DELETE FROM example.main.employees where id = 5;
```

### Response
#### Success Response (200)
- **total_changed** (uint64_t) - The total number of rows successfully deleted from the table.

#### Response Example
```json
{
  "total_changed": 1
}
```

### Caution
For an Airport managed table to perform a `DELETE` operation it must have a `rowid` pseudocolumn.

### Tip
Airport-managed tables lack the transactional guarantees of native DuckDB tables. When using the `INSERT` statement, all rows are sent to the Arrow Flight server where they are presumed to be immediately committed to storage. This differs from a standard SQL transaction that doesn’t commit data until `COMMIT` or `ROLLBACK` is issued.
The current philosophy of the Airport extension is to send the rows to the server. If the server fails to commit the rows during the RPC request, it will raise an Arrow Flight exception, causing the DuckDB transaction to abort.
This may change in the future.

## Arrow Flight Server Implementation Notes
If the table does has a rowid pseudocolumn the delete can be performed.
A `DoExchange` Arrow Flight RPC is made to delete rows. This allows the server to return rows (needed for the `RETURNING` clause), the rows may differ from the original input supplied. On the write stream of the `DoExchange` call only the rowid pseudocolumn will be sent to the server.

### Supplied gRPC Headers for `DoExchange` request.
- `airport-operation`: Set to `delete` to indicate the operation being performed.
- `return-chunks`: Set to `1` if a `RETURNING` clause is present; otherwise, `0`.

### Final Metadata Message
When the DuckDB client finishes writing to the write stream of the `DoExchange` RPC, the server is expected to return a single metadata message on the read stream that is serialized using `msgpack` with the following structure:

```
struct AirportChangedFinalMetadata
{
  uint64_t total_changed;
  MSGPACK_DEFINE_MAP(total_changed)
};
```

This message informs the client of the total number of rows successfully deleted from the table.
```

--------------------------------

### Get Airport Extension User Agent via airport_user_agent

Source: https://airport.query.farm/api

The `airport_user_agent` scalar function returns the current user agent header value of the Airport extension. This value is used to ensure compatibility with Arrow Flight servers.

```sql
SELECT airport_user_agent();
```

--------------------------------

### Select Query: BIGINT Table Benchmark

Source: https://airport.query.farm/benchmark

Benchmarks read operations from a remote table containing BIGINT data. Excellent performance, even at scale, demonstrates the efficiency of Apache Arrow Flight transport for fast data access.

```sql
-- This is a conceptual representation of the SQL operation
-- Actual benchmark would involve DuckDB SQL execution
-- SELECT * FROM remote_bigint_table WHERE some_condition;
```

--------------------------------

### Remote Table Creation: BIGINT Benchmark

Source: https://airport.query.farm/benchmark

Benchmarks the creation of a remote table from BIGINT data. Similar to string data, this process incurs single-threaded serialization and transport overhead, impacting overall ingestion performance for large datasets.

```sql
-- This is a conceptual representation of the SQL operation
-- Actual benchmark would involve DuckDB SQL execution
-- CREATE TABLE remote_bigint_table AS SELECT * FROM source_data_with_bigints;
```

--------------------------------

### Get Available Arrow Flights via airport_flights

Source: https://airport.query.farm/api

The `airport_flights` function returns a list of available Arrow Flights from a specified server. It accepts optional criteria for filtering, authentication tokens, and secret names for token retrieval. This is considered a lower-level interface.

```sql
SELECT * FROM airport_flights('grpc://127.0.0.1:8815', null);
```

--------------------------------

### Retrieving Catalog and Schema Information

Source: https://airport.query.farm/server_catalog_integration

Explains how database schema information is retrieved using the `list_schemas` Arrow Flight RPC action invoked via `DoAction`.

```APIDOC
## Retrieving Catalog and Schema Information

### Description
Database schema information is retrieved using an Arrow Flight RPC action named `list_schemas`. This action is invoked through the `DoAction` method provided by the Arrow Flight framework.

### Method

*   **RPC Action Name:** `list_schemas`
*   **Invocation:** Via `DoAction`
```

--------------------------------

### Output Result Structure for AirportSerializedCompressedContent (C++)

Source: https://airport.query.farm/server_action_list_schemas

Represents the `AirportSerializedCompressedContent` structure returned by the Arrow Flight server. It includes the uncompressed data length and the ZStandard compressed data.

```cpp
struct AirportSerializedCompressedContent
{
  // The uncompressed length of the data.
  uint32_t length;
  // The compressed data using ZStandard.
  std::string data;

  MSGPACK_DEFINE(length, data)
};

```

--------------------------------

### Connect to and Query Remote Data with Airport Extension

Source: https://airport.query.farm/index

This SQL demonstrates connecting to a remote database ('hello') using the Airport extension with TLS enabled. It then shows how to query data from 'greetings' and 'people' tables within a static schema, demonstrating joins and filtering.

```sql
-- Install the Airport extension and then load it into DuckDB
INSTALL airport FROM community;
LOAD AIRPORT;

-- Attach a database named 'hello'
ATTACH 'hello' (TYPE  AIRPORT, location 'grpc+tls://hello-airport.query.farm');

-- Jump into a static schema
USE hello.static;

-- First query using a join of two Airport tables.
SELECT
 greeting || ', ' || first_name || ' welcome to the Airport extension.' AS greeting
FROM greetings, people
WHERE people.language = greetings.language limit 3;
```

--------------------------------

### DuckDB SQL: Drop Schema with Airport Extension

Source: https://airport.query.farm/schema_drop

Demonstrates how to attach an Airport database and then drop a schema using a standard SQL DROP SCHEMA statement within a DuckDB session managed by the Airport extension. Assumes the Airport extension is installed and configured.

```sql
-- Attach an Airport database
ATTACH 'example' (TYPE AIRPORT, location 'grpc://localhost:50312/');

DROP SCHEMA example.main;
```

--------------------------------

### list_schemas RPC - Alternative Approach

Source: https://airport.query.farm/server_catalog_integration

Introduces the `list_schemas` RPC, invoked via `DoAction`, as a more suitable alternative to `ListFlights` for catalog integration, highlighting its flexible response delivery, comprehensive database representation, and efficient handling of dynamic schemas.

```APIDOC
## `list_schemas` RPC - Alternative Approach

### Description
The `list_schemas` RPC, invoked via `DoAction`, is presented as a superior alternative to Arrow Flight's `ListFlights` for catalog integration. This method offers flexible response delivery (inline or URL), enables efficient caching via SHA256 checksums, provides a comprehensive database structure, and handles dynamic schemas effectively.

### Benefits

1.  **Flexible Response Delivery:**
    *   Responses can be provided inline or via an external URL.
    *   Responses are validated and cached based on a SHA256 checksum, enabling CDN support and client-side caching.

2.  **Comprehensive Database Representation:**
    *   Returns the entire database structure, with each schema available inline or via URL.
    *   Allows efficient caching of immutable schemas.

3.  **Efficient Handling of Dynamic Schemas:**
    *   SHA256 checksums are optional for frequently changing schemas.
    *   Schemas without a SHA256 checksum are not cached by DuckDB.
```

--------------------------------

### Airport Extension Server Actions

Source: https://airport.query.farm/server_actions

This section details the various server actions supported by the Airport Extension for DuckDB when used with an Arrow Flight server. Each action is summarized with its function and whether it requires parameters.

```APIDOC
## Server Actions for Airport Extension

This document outlines the server actions available for the Airport Extension when integrating with an Arrow Flight server. These actions are invoked via the `DoAction` RPC.

### `add_column`

**Description**: Add a column to a table.

**Parameters**: No

### `add_constraint`

**Description**: Add a constraint to a field.

**Parameters**: No

### `add_field`

**Description**: Add a field to a structure.

**Parameters**: No

### `catalog_version`

**Description**: Get the current catalog version.

**Parameters**: No

### `change_column_type`

**Description**: Change the type of a column.

**Parameters**: No

### `column_statistics`

**Description**: Get column-level statistics for a flight.

**Parameters**: No

### `create_schema`

**Description**: Create a new schema.

**Parameters**: No

### `create_table`

**Description**: Create a new table.

**Parameters**: No

### `create_transaction`

**Description**: Create a new transaction identifier.

**Parameters**: No

### `drop_not_null`

**Description**: Drop NOT NULL constraint from a field.

**Parameters**: No

### `drop_schema`

**Description**: Drop a schema.

**Parameters**: No

### `drop_table`

**Description**: Drop a table.

**Parameters**: No

### `endpoints`

**Description**: Get the endpoints for a specific flight.

**Parameters**: Yes

### `list_schemas`

**Description**: List all schemas in the database.

**Parameters**: Yes

### `remove_column`

**Description**: Remove a column from a table.

**Parameters**: No

### `remove_field`

**Description**: Remove a field from a structure.

**Parameters**: No

### `rename_column`

**Description**: Rename a column.

**Parameters**: No

### `rename_field`

**Description**: Rename a field in a structure.

**Parameters**: No

### `rename_table`

**Description**: Rename a table.

**Parameters**: No

### `set_default`

**Description**: Set a default value for a field.

**Parameters**: No

### `set_not_null`

**Description**: Set a field to NOT NULL.

**Parameters**: No

### `table_function_flight_info`

**Description**: Get FlightInfo for a table-returning function.

**Parameters**: No

```

--------------------------------

### Train Sales Forecast Model (SQL)

Source: https://airport.query.farm/motivation

This SQL statement demonstrates how to train a sales forecast model using a SQL function. It calls the 'forecast_sales' function with 'product_id', 'sales_date', and 'quantity_sold' from the 'sales_data' table. The output would be the result of the forecasting function.

```sql
SELECT forecast_sales(product_id, sales_date, quantity_sold)
FROM sales_data;
```

--------------------------------

### Define Drop Table Action Parameters (C++)

Source: https://airport.query.farm/server_action_drop_table

Defines the structure for parameters used in the `drop_table` action. It specifies the table type, catalog, schema, name, and an option to ignore if the table is not found. This structure is serialized using msgpack.

```cpp
struct DropItemActionParameters
{
  std::string type;

  std::string catalog_name;
  std::string schema_name;
  std::string name;

  bool ignore_not_found;

  MSGPACK_DEFINE_MAP(type, catalog_name, schema_name, name, ignore_not_found)
};

```

--------------------------------

### Define AirportGetCatalogVersionParams for Catalog Version Action

Source: https://airport.query.farm/server_action_catalog_version

Defines the input parameters for the `catalog_version` action. It takes a single `msgpack` serialized parameter, `catalog_name`, which specifies the catalog to query. This structure is used by DuckDB to communicate with the Arrow Flight server.

```cpp
struct AirportGetCatalogVersionParams
{
  string catalog_name;
  MSGPACK_DEFINE_MAP(catalog_name);
};

```

--------------------------------

### Define Airport Catalog Version Parameters (C++)

Source: https://airport.query.farm/server_action_create_transaction

Defines the structure for input parameters when retrieving the airport catalog version. It includes the catalog name and uses MSGPACK_DEFINE_MAP for serialization. This is a C++ structure definition.

```c++
struct AirportGetCatalogVersionParams
{
  string catalog_name;
  MSGPACK_DEFINE_MAP(catalog_name);
};
```

--------------------------------

### Create data:// URI for read_csv using PyArrow (Python)

Source: https://airport.query.farm/server_action_endpoints

Demonstrates how to construct a 'data://' URI to call the 'read_csv' function using PyArrow. It involves serializing function arguments and parameters into an Arrow IPC table and then into a MessagePack structure.

```python
import pyarrow as pa

dict_to_msgpack_duckdb_call_data_uri(
    {
        "function_name": "read_csv",
        # So arguments could be a record batch.
        "data": serialize_arrow_ipc_table(
            pa.Table.from_pylist(
                [
                    {
                        "arg_0": [
                            "/tmp/example-0.csv",
                            "/tmp/example-1.csv",
                            "/tmp/example-2.csv",
                        ],
                        "hive_partitioning": False,
                    }
                ],
                schema=pa.schema(
                    [
                        pa.field("arg_0", pa.list_(pa.string())),
                        pa.field("hive_partitioning", pa.bool_()),
                    ]
                ),
            )
        ),
    }
)
```

--------------------------------

### Root Catalog Structure for AirportSerializedCatalogRoot (C++)

Source: https://airport.query.farm/server_action_list_schemas

Defines the `AirportSerializedCatalogRoot` structure, which represents the deserialized catalog content after decompression. It can optionally contain the entire catalog contents or a list of schemas.

```cpp
struct AirportSerializedCatalogRoot
{
  // The contents of the catalog itself, this is optional, if its
  // more efficient to provide the entire catalog at once rather than
  // having each schema listed individually.
  AirportSerializedContentsWithSHA256Hash contents;
  // A list of schemas.
  std::vector<AirportSerializedSchema> schemas;

  MSGPACK_DEFINE_MAP(contents, schemas)
};

```

--------------------------------

### DuckDB Airport Extension: Attaching and Querying Remote Tables

Source: https://airport.query.farm/table_select

Demonstrates how to attach a remote Airport database and query tables using standard DuckDB SQL. It shows basic table selection and time-travel queries based on timestamp or version.

```sql
-- Attach an Airport database
ATTACH 'example' (TYPE AIRPORT, location 'grpc://localhost:50312/');

-- Assume that there is a `main` schema
-- already in the `example` database
CREATE TABLE example.main.employees (
  name varchar,
  id integer
);

SELECT * FROM example.main.employees;

-- Queries that specify a point in time
-- or version of the table are supported, if
-- the Arrow flight server supports it.
SELECT * FROM example.main.exployees AT (TIMESTAMP => TIMESTAMP '2020-01-01');
SELECT * FROM example.main.employees AT (VERSION => 42);
```

--------------------------------

### Scalar Function: Echo BIGINT Benchmark

Source: https://airport.query.farm/benchmark

Benchmarks a scalar function that echoes a BIGINT. This operation is nearly zero-cost on the server side, with a BIGINT input echoed back as output. It achieves high throughput, demonstrating efficient handling of basic data types.

```sql
-- This is a conceptual representation of the SQL operation
-- Actual benchmark would involve DuckDB SQL execution
-- SELECT airport.echo_bigint(some_bigint_value) FROM large_table;
```

--------------------------------

### Query Yesterday's Total Revenue (SQL)

Source: https://airport.query.farm/motivation

This SQL query calculates the sum of total prices for orders placed yesterday. It assumes a 'sales_data' table with 'total_price' and 'order_date' columns. The result is a single value representing yesterday's total revenue.

```sql
SELECT SUM(total_price)
FROM sales_data
WHERE order_date = CURRENT_DATE - INTERVAL 1 DAY;
```

--------------------------------

### Select Query: 32-byte String Table Benchmark

Source: https://airport.query.farm/benchmark

Benchmarks read operations from a remote table containing 32-byte strings. High read speeds indicate efficient decoding and data retrieval mechanisms, making it suitable for read-heavy analytical workloads.

```sql
-- This is a conceptual representation of the SQL operation
-- Actual benchmark would involve DuckDB SQL execution
-- SELECT * FROM remote_string_table WHERE some_condition;
```

--------------------------------

### List Schemas

Source: https://airport.query.farm/server_action_list_schemas

The `list_schemas` action is used by DuckDB to determine the contents of a database attached via Airport. The Arrow Flight server returns information about the schemas that exist in the database as well as all of the tables, scalar functions and table returning functions.

```APIDOC
## POST /list_schemas

### Description
Retrieves information about schemas, tables, scalar functions, and table-returning functions within an attached database.

### Method
POST

### Endpoint
/list_schemas

### Parameters
#### Request Body
- **catalog_name** (string) - Required - The name of the catalog to query.

### Request Example
```json
{
  "catalog_name": "my_catalog"
}
```

### Response
#### Success Response (200)
- **length** (uint32) - The uncompressed length of the data.
- **data** (string) - The ZStandard compressed msgpack data containing `AirportSerializedCatalogRoot` information.

#### Response Example
```json
{
  "length": 12345,
  "data": "compressed_data_string"
}
```

### Schema Serialization Methods
Content can be provided inline or via a URL with SHA256 validation.

#### `AirportSerializedContentsWithSHA256Hash` Structure
- **sha256** (string) - The SHA256 checksum of the data or URL.
- **url** (string, optional) - The external URL to fetch the contents from.
- **serialized** (string, optional) - The inline serialized contents.

#### Catalog Inline Serialization
- A ZStandard compressed msgpack array of serialized Apache Arrow `FlightInfo` structures.

#### Schema Inline Serialization
- A ZStandard compressed msgpack array of serialized Apache Arrow `FlightInfo` structures.
```

--------------------------------

### Create Transaction Action

Source: https://airport.query.farm/server_action_create_transaction

The `create_transaction` action is used to obtain a new transaction identifier. It accepts a single msgpack serialized parameter.

```APIDOC
## `create_transaction` Action

### Description
Used to obtain a new transaction identifier. A single `msgpack` serialized parameter is passed to the action.

### Method
POST

### Endpoint
/websites/airport_query_farm/create_transaction

### Parameters
#### Request Body
- **params** (object) - Required - A msgpack serialized object containing the following fields:
  - **catalog_name** (string) - Required - The name of the catalog.

### Request Example
```
{
  "catalog_name": "example_catalog"
}
```

### Response
#### Success Response (200)
- **identifier** (string) - The unique transaction identifier.

#### Response Example
```json
{
  "identifier": "a1b2c3d4e5f6"
}
```
```

--------------------------------

### Content Serialization Structure AirportSerializedContentsWithSHA256Hash (C++)

Source: https://airport.query.farm/server_action_list_schemas

Defines the `AirportSerializedContentsWithSHA256Hash` structure used for schema or catalog content. It supports providing content inline or via a URL, with SHA256 checksum validation for integrity.

```cpp
// This is a generic type that applies a SHA256
// checksum to the data it contains.
//
// The data can either be provied inline by
// inside of the serialized field, or it can
// be retrieved from the specified URL.
//
// URLs are considered to be immutable, and
// their contents may be cached on disk.
struct AirportSerializedContentsWithSHA256Hash
{
  // The SHA256 of the serialized contents.
  // or the external url.
  std::string sha256;

  // The external URL where the contents should be obtained.
  std::optional<std::string> url;

  // The inline serialized contents.
  std::optional<std::string> serialized;

  MSGPACK_DEFINE_MAP(sha256, url, serialized)
};

```

--------------------------------

### List Databases with airport_databases

Source: https://airport.query.farm/api

The airport_databases function retrieves a list of attachable databases from an Arrow Flight server. It requires the server location as an argument and returns a table with database names and optional descriptions.

```sql
SELECT * FROM airport_databases('grpc://localhost:8815/');
```