Interfaz Arrow Flight

​

Descripción general

• Ejecutar consultas SQL y recuperar resultados en formato Apache Arrow.
• Insertar datos en tablas con el formato Arrow.
• Consultar metadatos (catálogos, esquemas, tablas y claves primarias) mediante comandos de Flight SQL.
• Crear, vincular, ejecutar y cerrar sentencias preparadas en el servidor mediante Flight SQL.
• Administrar sesiones y ajustes mediante acciones de Flight SQL.
• Cifrado TLS y autenticación mediante nombre de usuario y contraseña.
• Recuperación incremental de resultados mediante PollFlightInfo.
• Cancelación de consultas mediante CancelFlightInfo.

​

Habilitar el servidor Arrow Flight

<clickhouse>
    <arrowflight_port>9090</arrowflight_port>
</clickhouse>

{} <Information> Application: Arrow Flight compatibility protocol: 0.0.0.0:9090

​

Configuración de TLS

<clickhouse>
    <arrowflight_port>9090</arrowflight_port>
    <arrowflight>
        <enable_ssl>true</enable_ssl>
        <ssl_cert_file>/path/to/server-cert.pem</ssl_cert_file>
        <ssl_key_file>/path/to/server-key.pem</ssl_key_file>
    </arrowflight>
</clickhouse>

​

Autenticación

​

Autenticación básica

​

Autenticación con token Bearer

​

Ejemplo de Python

import pyarrow.flight as flight

client = flight.FlightClient("grpc://localhost:9090")

# La autenticación básica devuelve un token Bearer para llamadas posteriores
token_pair = client.authenticate_basic_token("default", "")
options = flight.FlightCallOptions(headers=[token_pair])

import pyarrow.flight as flight

with open("ca-cert.pem", "rb") as f:
    tls_root_certs = f.read()

client = flight.FlightClient(
    "grpc+tls://localhost:9090",
    tls_root_certs=tls_root_certs,
)

token_pair = client.authenticate_basic_token("default", "password")
options = flight.FlightCallOptions(headers=[token_pair])

​

Gestión de sesiones

​

Referencia de la configuración del servidor

​

Métodos RPC compatibles

​

GetFlightInfo

• PATH descriptor: Una ruta de un solo componente interpretada como nombre de tabla. Genera SELECT * FROM <table>.
• CMD descriptor: Una cadena de consulta SQL sin procesar o un comando protobuf serializado de Flight SQL (consulta Comandos de Flight SQL).

# Consulta por nombre de tabla
descriptor = flight.FlightDescriptor.for_path("my_table")
info = client.get_flight_info(descriptor, options)

# Consulta por SQL
descriptor = flight.FlightDescriptor.for_command(
    "SELECT * FROM my_table WHERE id > 100"
)
info = client.get_flight_info(descriptor, options)

# Recuperar resultados
for endpoint in info.endpoints:
    reader = client.do_get(endpoint.ticket, options)
    table = reader.read_all()
    print(table.to_pandas())

​

PollFlightInfo

• Un FlightInfo con endpoints para todos los bloques de datos disponibles hasta ese momento.
• Un FlightDescriptor para el siguiente sondeo (si se esperan más resultados).

​

GetSchema

descriptor = flight.FlightDescriptor.for_command(
    "SELECT 1 AS x, 'hello' AS y"
)
schema_result = client.get_schema(descriptor, options)
schema = schema_result.schema
print(schema)  # x: int32, y: string

​

DoGet

• Un ticket devuelto por GetFlightInfo o PollFlightInfo.
• Una cadena con una consulta SQL sin procesar como valor del ticket.

# Usando un ticket de GetFlightInfo
reader = client.do_get(endpoint.ticket, options)
table = reader.read_all()

# Usando una consulta SQL sin procesar como ticket
ticket = flight.Ticket("SELECT number FROM system.numbers LIMIT 10")
reader = client.do_get(ticket, options)
table = reader.read_all()

​

DoPut

schema = pa.schema([("id", pa.int64()), ("name", pa.string())])
batch = pa.record_batch(
    [pa.array([1, 2, 3]), pa.array(["Alice", "Bob", "Charlie"])],
    schema=schema,
)

descriptor = flight.FlightDescriptor.for_path("my_table")
writer, _ = client.do_put(descriptor, schema, options)
writer.write_batch(batch)
writer.close()

descriptor = flight.FlightDescriptor.for_command(
    "INSERT INTO my_table FORMAT Arrow"
)
writer, _ = client.do_put(descriptor, schema, options)
writer.write_batch(batch)
writer.close()

​

DoAction

​

CancelFlightInfo

# Inicia una consulta de larga duración mediante PollFlightInfo y luego cancélala
cancel_request = flight.CancelFlightInfoRequest(info)
result = client.cancel_flight_info(cancel_request, options)
# result.status es CancelStatus.CANCELLED si se realizó correctamente

​

SetSessionOptions

​

GetSessionOptions

​

CreatePreparedStatement

• dataset_schema: esquema del conjunto de resultados.
• parameter_schema: esquema de los parámetros de la sentencia.

• La inferencia sustituye cada ? por NULL, de modo que un marcador de posición que determina una columna del resultado recibe su tipo a partir de ese NULL y no del valor que enlace después. SELECT ? AS x infiere una columna de tipo Nothing, pero al enlazar 5 se sirve un UInt8. Un marcador de posición usado únicamente en un predicado, como en SELECT id, name FROM t WHERE id = ?, no presenta este problema, porque los tipos del resultado provienen de la tabla.
• Una columna sin equivalente en Arrow toma su tipo de Arrow de output_format_arrow_unsupported_types, que cada llamada resuelve a partir de la sesión desde la que se realiza. Como un identificador pertenece al usuario y no a una sola sesión, una llamada posterior puede resolverlo de forma distinta y servir binary donde se había anunciado utf8, o al revés. Establecer el modo dentro de la propia consulta preparada lo fija para ambos casos.

• > 0: usa el valor configurado como duración de la sentencia. La expiración se renueva con cada solicitud, tanto para las sentencias asociadas a una sesión como para las sin sesión.
• 0: las sentencias preparadas no expiran automáticamente.
• -1 (predeterminado): si la sentencia se crea en una sesión, su duración sigue el tiempo de espera de esa sesión y se renueva con cada solicitud de esa sesión. Si la sentencia se crea sin una sesión, no expira automáticamente.

​

ClosePreparedStatement

• Si x-clickhouse-session-id está presente, cierra todas las sentencias preparadas del usuario autenticado en esa sesión.
• Si no hay ningún ID de sesión, cierra solo las sentencias preparadas sin sesión del usuario autenticado.

​

Comandos de Flight SQL

​

Admitido a través de GetFlightInfo / GetSchema

​

Compatibles mediante DoPut

​

No admitido por ClickHouse

​

Ejemplo completo

import pyarrow as pa
import pyarrow.flight as flight

# Conectar y autenticar
client = flight.FlightClient("grpc://localhost:9090")
token = client.authenticate_basic_token("default", "")
options = flight.FlightCallOptions(headers=[token])

# Insertar datos usando DoPut con un descriptor PATH
schema = pa.schema([("id", pa.uint32()), ("value", pa.string())])
batch = pa.record_batch(
    [pa.array([1, 2, 3], type=pa.uint32()), pa.array(["a", "b", "c"])],
    schema=schema,
)
descriptor = flight.FlightDescriptor.for_path("test")
writer, _ = client.do_put(descriptor, schema, options)
writer.write_batch(batch)
writer.close()

# Consultar datos usando GetFlightInfo + DoGet
descriptor = flight.FlightDescriptor.for_command(
    "SELECT * FROM test ORDER BY id"
)
info = client.get_flight_info(descriptor, options)
for endpoint in info.endpoints:
    reader = client.do_get(endpoint.ticket, options)
    table = reader.read_all()
    print(table.to_pandas())

   id value
0   1     a
1   2     b
2   3     c

​

Formato de datos

• Flight SQL fija el esquema de sus respuestas de metadatos. CommandGetTables, por ejemplo, debe devolver catalog_name: utf8, db_schema_name: utf8, table_name: utf8 not null, table_type: utf8 not null, table_schema: bytes not null. Permitir que una configuración de sesión convirtiera esas columnas utf8 en binary haría que ClickHouse dejara de cumplir la especificación para todos los controladores de Flight SQL, y además cambiaría el esquema por tabla que ClickHouse anuncia dentro de table_schema.
• Un cliente de Flight obtiene el esquema y los datos en llamadas separadas (GetFlightInfo o GetSchema, y después DoGet). Cualquier opción capaz de cambiar el esquema abre la puerta a que el esquema anunciado y el stream entregado no coincidan si la sesión cambia entretanto.

​

Compatibilidad

• Python (pyarrow)
• Java (org.apache.arrow.flight)
• C++ (arrow::flight)
• Go (apache/arrow/go)
• controladores ADBC (Arrow Database Connectivity)
• DBeaver y otras herramientas compatibles con Flight SQL

​

Funciones de ArrowFlight del lado del cliente

• motor de tabla ArrowFlight
• función de tabla arrowFlight

​

Véase también

• Especificación de Apache Arrow Flight
• Especificación de Apache Arrow Flight SQL
• Formato Arrow en ClickHouse