`를 생성합니다.
* **CMD 디스크립터**: 원시 SQL 쿼리 문자열 또는 직렬화된 Flight SQL protobuf 명령입니다([Flight SQL Commands](#flight-sql-commands) 참조).
쿼리는 전체가 실행되며, 결과는 서버 측 티켓에 저장됩니다. 각 데이터 block은 별도의 엔드포인트/티켓을 생성하므로, 클라이언트는 데이터를 병렬로 검색할 수 있습니다.
```python theme={null}
# 테이블 이름으로 쿼리
descriptor = flight.FlightDescriptor.for_path("my_table")
info = client.get_flight_info(descriptor, options)
# SQL로 쿼리
descriptor = flight.FlightDescriptor.for_command(
"SELECT * FROM my_table WHERE id > 100"
)
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())
```
### PollFlightInfo
장시간 실행되는 쿼리의 결과를 점진적으로 가져올 수 있도록 합니다. 전체 쿼리가 완료될 때까지 기다리는 `GetFlightInfo`와 달리, `PollFlightInfo`는 결과를 블록 단위로 반환합니다.
첫 번째 호출 시 쿼리 실행이 시작됩니다. 응답에는 다음이 포함됩니다:
* 현재까지 사용 가능한 데이터 블록의 endpoint가 포함된 `FlightInfo`
* 다음 폴링에 사용할 `FlightDescriptor`(추가 결과가 예상되는 경우)
이후에는 반환된 디스크립터로 추가 호출을 수행해 다음 블록들을 가져옵니다. 더 이상 사용할 수 있는 데이터가 없으면 응답에는 다음 디스크립터가 포함되지 않습니다.
현재 구현은 데이터 블록을 사용할 수 있을 때까지 대기하며, 데이터 없이 즉시 반환하지는 않습니다.
### GetSchema
전체 쿼리를 실행하지 않고 쿼리 결과의 Arrow 스키마를 반환합니다. `GetFlightInfo`와 동일한 디스크립터 유형을 지원합니다.
```python theme={null}
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
지정된 티켓에 대한 데이터를 가져옵니다. 다음 중 하나를 받습니다:
* `GetFlightInfo` 또는 `PollFlightInfo`에서 반환된 티켓
* 티켓 값으로 전달되는 원시 SQL 쿼리 문자열
```python theme={null}
# GetFlightInfo에서 반환된 티켓 사용
reader = client.do_get(endpoint.ticket, options)
table = reader.read_all()
# 티켓으로 SQL 쿼리 직접 사용
ticket = flight.Ticket("SELECT number FROM system.numbers LIMIT 10")
reader = client.do_get(ticket, options)
table = reader.read_all()
```
### DoPut
데이터를 ClickHouse로 전송합니다. `FlightDescriptor`와 Arrow 레코드 배치 스트림을 인수로 받습니다.
**테이블 이름으로 삽입** (PATH 디스크립터):
```python theme={null}
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()
```
**SQL을 통한 삽입** (CMD 디스크립터):
```python theme={null}
descriptor = flight.FlightDescriptor.for_command(
"INSERT INTO my_table FORMAT Arrow"
)
writer, _ = client.do_put(descriptor, schema, options)
writer.write_batch(batch)
writer.close()
```
**Flight SQL `CommandStatementUpdate`를 통한 DDL/DML 실행:**
Flight SQL 클라이언트는 DDL/DML SQL 문(CREATE, INSERT, ALTER 등)을 실행할 때 `CommandStatementUpdate`를 사용합니다. 응답에는 영향을 받은 행 수가 포함됩니다.
**Flight SQL `CommandStatementIngest`를 통한 대량 수집:**
기존 테이블에 데이터를 추가하는 작업만 지원됩니다(`TABLE_NOT_EXIST_OPTION_FAIL` + `TABLE_EXISTS_OPTION_APPEND`). 이 명령에서는 카탈로그와 임시 테이블을 지원하지 않습니다.
`transaction_id`는 `CommandStatementUpdate`와 `CommandStatementIngest` 모두에서 지원되지 않습니다. 이를 제공하면 ClickHouse는 `NotImplemented` 오류를 반환합니다.
데이터 전송에는 `Arrow` 형식만 허용됩니다. SQL에서 다른 포맷을 지정하면(예: `FORMAT JSON`) 오류가 발생합니다.
### DoAction
명명된 actions를 실행합니다. 지원되는 actions는 다음과 같습니다:
#### CancelFlightInfo
`FlightInfo`와 연결된 실행 중인 쿼리를 취소합니다. 쿼리 ID는 `FlightInfo`의 `app_metadata` 필드에서 추출됩니다. 또한 해당 쿼리와 연결된 모든 폴링 디스크립터도 취소합니다.
```python theme={null}
# PollFlightInfo를 통해 장기 실행 쿼리를 시작한 후 취소합니다
cancel_request = flight.CancelFlightInfoRequest(info)
result = client.cancel_flight_info(cancel_request, options)
# 성공 시 result.status는 CancelStatus.CANCELLED입니다
```
#### SetSessionOptions
현재 세션의 ClickHouse 서버 설정을 지정합니다. `x-clickhouse-session-id` 헤더를 통해 세션 ID가 설정되어 있어야 합니다.
지원되는 값 타입: string, boolean, integer, double, string list입니다.
설정 이름을 인식할 수 없으면 오류 `INVALID_NAME`이 반환됩니다. 값을 파싱할 수 없으면 오류 `INVALID_VALUE`가 반환됩니다.
#### GetSessionOptions
현재 세션의 모든 ClickHouse 설정과 해당 값을 반환합니다. 설정 이름을 문자열 값에 매핑한 맵을 반환합니다(내부적으로 `system.settings`를 쿼리합니다).
#### CreatePreparedStatement
서버 측 prepared statement를 생성하고 statement handle을 반환합니다. 요청에는 `?` 플레이스홀더가 포함된 SQL 쿼리 텍스트가 들어 있습니다.
이 작업에서는 `transaction_id`를 지원하지 않습니다. 이를 제공하면 ClickHouse는 `NotImplemented` 오류를 반환합니다.
쿼리 SQL 문의 경우 응답에 다음이 포함될 수 있습니다:
* `dataset_schema`: result set의 스키마
* `parameter_schema`: SQL 문 매개변수의 스키마
유효한 쿼리에서 스키마 추론이 실패하더라도(예를 들어 플레이스홀더를 `NULL`로 대체하는 것이 해당 쿼리에서 유효하지 않은 경우) ClickHouse는 여전히 prepared statement를 생성하고 `dataset_schema` 없이 handle을 반환합니다.
Prepared statements는 단일 세션이 아니라 인증된 사용자가 소유합니다. 동일한 사용자로 여러 세션을 열면 그 세션들 중 어느 세션에서든 동일한 statement handle을 실행, 다시 바인드, 종료할 수 있습니다.
다른 사용자는 자신이 생성하지 않은 statement handle을 실행, 바인드 또는 종료할 수 없습니다.
`arrowflight.prepared_statements_lifetime_seconds`는 만료 동작을 제어합니다:
* `> 0`: 구성된 값을 statement의 수명으로 사용합니다. 세션에 바인딩된 statement와 세션이 없는 statement 모두에서 각 요청 시 만료 시간이 갱신됩니다.
* `0`: prepared statements는 자동으로 만료되지 않습니다.
* `-1` (기본값): statement가 세션에서 생성되면 수명은 해당 세션 timeout을 따르며, 그 세션의 각 요청 시 갱신됩니다. statement가 세션 없이 생성되면 자동으로 만료되지 않습니다.
만료된 statements는 제거되며 더 이상 `arrowflight.max_prepared_statements_per_user`에 포함되지 않습니다.
#### ClosePreparedStatement
요청에 비어 있지 않은 statement handle이 포함된 경우 prepared statement를 닫고, 관련 서버 측 리소스를 해제합니다.
ClickHouse는 handle이 비어 있을 때 `ClosePreparedStatement`를 사용한 일괄 종료도 지원합니다.
* `x-clickhouse-session-id`가 있으면 해당 세션에서 인증된 사용자의 모든 prepared statement를 닫습니다.
* 세션 ID가 없으면 인증된 사용자의 세션 없는 prepared statement만 닫습니다.
prepared statement가 세션(`x-clickhouse-session-id`를 통해)에서 생성된 경우, 해당 세션이 종료될 때 자동으로 함께 닫힙니다.
## Flight SQL 명령
`CMD` 디스크립터에 직렬화된 [Flight SQL protobuf](https://arrow.apache.org/docs/format/FlightSql.html) 메시지가 포함된 경우, ClickHouse는 다음 명령을 처리합니다:
### GetFlightInfo / GetSchema에서 지원
| Command | Description |
| ------------------------------- | -------------------------------------------------------------------- |
| `CommandStatementQuery` | 임의의 SQL 쿼리를 실행합니다. `transaction_id`는 지원되지 않습니다. |
| `CommandGetSqlInfo` | 서버 메타데이터(이름, 버전, Arrow 버전, capability)를 가져옵니다. |
| `CommandGetCatalogs` | 카탈로그를 나열합니다. 빈 결과를 반환합니다(ClickHouse는 카탈로그를 사용하지 않습니다). |
| `CommandGetDbSchemas` | 데이터베이스를 나열합니다. 선택적 `db_schema_filter_pattern`(SQL `LIKE` 패턴)을 지원합니다. |
| `CommandGetTables` | 테이블을 나열합니다. 스키마, 테이블 이름, 테이블 타입, 선택적 스키마 포함 여부에 대한 필터를 지원합니다. |
| `CommandGetTableTypes` | 테이블 엔진 타입을 나열합니다(`system.table_engines` 기준). |
| `CommandGetPrimaryKeys` | 지정된 테이블의 프라이머리 키 컬럼을 가져옵니다. |
| `CommandPreparedStatementQuery` | 핸들로 준비된 `SELECT` 스타일 구문을 실행합니다. |
### DoPut을 통해 지원됩니다
| Command | Description |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CommandStatementUpdate` | DDL/DML 문(CREATE, INSERT, ALTER 등)을 실행합니다. 영향을 받은 행 수를 반환합니다. `transaction_id`는 지원되지 않습니다. |
| `CommandStatementIngest` | 기존 테이블에 Arrow 데이터를 대량 삽입합니다. append 모드만 지원됩니다. `transaction_id`는 지원되지 않습니다. |
| `CommandPreparedStatementQuery` | `DoPut`으로 전송할 때 prepared statement의 매개변수 값을 바인딩한 뒤, statement handle이 포함된 `DoPutPreparedStatementResult`를 반환합니다. 매개변수 집합은 1개(행 1개)만 허용되며, 바인딩된 값의 개수는 `?` placeholder의 개수와 정확히 일치해야 합니다. |
| `CommandPreparedStatementUpdate` | handle로 prepared DDL/DML 문을 실행하고 영향을 받은 행 수를 반환합니다. |
### ClickHouse에서 지원되지 않음
다음 명령은 ClickHouse에서 제공하지 않는 기능에 해당하므로 Arrow Flight SQL 인터페이스에서 지원되지 않습니다.
| Command | Reason |
| ------------------------------- | ------------------------------------------------------------------------- |
| `CommandGetCrossReference` | ClickHouse는 관계형 데이터베이스가 아니며 외래 키 제약 조건을 구현하지 않으므로 교차 참조 메타데이터를 제공하지 않습니다. |
| `CommandGetExportedKeys` | ClickHouse는 관계형 데이터베이스가 아니며 외래 키 제약 조건을 구현하지 않으므로 내보낸 키 메타데이터를 제공하지 않습니다. |
| `CommandGetImportedKeys` | ClickHouse는 관계형 데이터베이스가 아니며 외래 키 제약 조건을 구현하지 않으므로 가져온 키 메타데이터를 제공하지 않습니다. |
| `CommandStatementSubstraitPlan` | ClickHouse는 Substrait plan을 지원하지 않습니다. |
## 전체 예시
```python title="Query" theme={null}
import pyarrow as pa
import pyarrow.flight as flight
# 연결 및 인증
client = flight.FlightClient("grpc://localhost:9090")
token = client.authenticate_basic_token("default", "")
options = flight.FlightCallOptions(headers=[token])
# PATH 디스크립터를 사용하여 DoPut으로 데이터 삽입
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()
# 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())
```
```text title="Response" theme={null}
id value
0 1 a
1 2 b
2 3 c
```
## 데이터 포맷
모든 데이터는 Apache Arrow IPC 포맷으로 전송됩니다. `Arrow` 형식만 지원되며, 다른 ClickHouse 포맷(예: `FORMAT JSON`, `FORMAT CSV`)을 지정하면 오류가 발생합니다.
직렬화 시 ClickHouse 데이터 타입은 Arrow 타입으로 매핑됩니다. 설정 `output_format_arrow_unsupported_types_as_binary`는 지원되지 않는 ClickHouse 타입을 바이너리 blob으로 직렬화할지 여부를 제어합니다.
## 호환성
Arrow Flight 인터페이스는 Arrow Flight 또는 Arrow Flight SQL 프로토콜을 지원하는 모든 클라이언트나 도구와 호환됩니다. 예를 들면 다음과 같습니다.
* Python (`pyarrow`)
* Java (`org.apache.arrow.flight`)
* C++ (`arrow::flight`)
* Go (`apache/arrow/go`)
* ADBC (Arrow Database Connectivity) 드라이버
* DBeaver 및 Flight SQL을 지원하는 기타 도구
사용하는 도구에 네이티브 ClickHouse 커넥터가 있다면(예: JDBC, ODBC, 네이티브 프로토콜), 성능 또는 포맷 호환성 때문에 Arrow Flight가 특별히 필요한 경우가 아니라면 해당 커넥터를 사용하는 것이 좋습니다.
## 클라이언트 측 ArrowFlight 기능
ClickHouse는 외부 Arrow Flight 서버에서 데이터를 읽는 Flight 클라이언트로도 사용할 수 있습니다. 다음을 참조하십시오.
* [ArrowFlight 테이블 엔진](/ko/reference/engines/table-engines/integrations/arrowflight)
* [arrowFlight 테이블 함수](/ko/reference/functions/table-functions/arrowflight)
## 관련 항목
* [Apache Arrow Flight 명세](https://arrow.apache.org/docs/format/Flight.html)
* [Apache Arrow Flight SQL 명세](https://arrow.apache.org/docs/format/FlightSql.html)
* [ClickHouse의 Arrow 형식](/ko/reference/formats/Arrow/Arrow)