diff --git a/.gitignore b/.gitignore index 3a8cabc..f310b3c 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,3 @@ /target .idea +.cargo/ diff --git a/CHANGELOG.md b/CHANGELOG.md index a41d970..9fee020 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,8 +11,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 * Implemented `Connection::get_option_string()` for `OptionConnection::AutoCommit` (always `"true"`, as ClickHouse has no transactions) and `OptionConnection::CurrentCatalog` (always empty, as ClickHouse has no catalog level above the database). ([#65]) +* Implemented `Connection::get_info()` for driver/vendor metadata ([#69]). [#65]: https://github.com/ClickHouse/adbc_clickhouse/pull/65 +[#69]: https://github.com/ClickHouse/adbc_clickhouse/pull/69 ## [0.1.2] - 2026-11-06 diff --git a/README.md b/README.md index 15f798d..c1c8dec 100644 --- a/README.md +++ b/README.md @@ -19,6 +19,7 @@ However, the core query flow is supported: * Creating a `Driver` and `Database` * Setting URL, username and password on the `Database` * Creating a `Connection` and `Statement` +* Querying driver/vendor metadata with `Connection::get_info()` * Setting a query with `Statement::set_sql_query()` and binding parameters with `Statement::bind()` * Binding a statement in streaming insert mode with `Statement::bind_stream()` * Executing a statement with `Statement::execute()` or `Statement::execute_update()` diff --git a/src/info.rs b/src/info.rs new file mode 100644 index 0000000..83424ad --- /dev/null +++ b/src/info.rs @@ -0,0 +1,147 @@ +//! Helpers for building [`Connection::get_info`][adbc_core::Connection::get_info] results. +//! +//! The result schema is defined by [`adbc_core::schemas::GET_INFO_SCHEMA`]. + +use adbc_core::error::{Error, Status}; +use adbc_core::options::InfoCode; +use adbc_core::schemas::GET_INFO_SCHEMA; +use arrow_array::builder::{ + ArrayBuilder, BooleanBuilder, Int32Builder, Int64Builder, ListBuilder, MapBuilder, + MapFieldNames, StringBuilder, UInt32Builder, +}; +use arrow_array::{ArrayRef, RecordBatch, RecordBatchIterator, RecordBatchReader, UnionArray}; +use arrow_buffer::ScalarBuffer; +use arrow_schema::{DataType, UnionMode}; +use std::collections::HashSet; +use std::sync::Arc; + +type Result = std::result::Result; + +/// Builds a dense-union `get_info` result matching [`GET_INFO_SCHEMA`]. +/// +/// Pattern adapted from the ADBC Driver Foundry [`InfoBuilder`][info-builder]. +/// +/// [info-builder]: https://github.com/adbc-drivers/driverbase-rs/blob/main/driverbase/src/lib.rs +pub(crate) struct InfoBuilder { + info_name: UInt32Builder, + type_id: Vec, + offset: Vec, + string_value: StringBuilder, + bool_value: BooleanBuilder, + int64_value: Int64Builder, + int32_bitmask: Int32Builder, + string_list: ListBuilder, + int32_to_int32_list_map: MapBuilder>, +} + +impl InfoBuilder { + const CODE_STRING: i8 = 0; + const CODE_BOOL: i8 = 1; + const CODE_INT64: i8 = 2; + + pub(crate) fn new() -> Self { + Self { + info_name: UInt32Builder::new(), + type_id: Vec::new(), + offset: Vec::new(), + string_value: StringBuilder::new(), + bool_value: BooleanBuilder::new(), + int64_value: Int64Builder::new(), + int32_bitmask: Int32Builder::new(), + string_list: ListBuilder::new(StringBuilder::new()), + // Match `GET_INFO_SCHEMA` field names (`key`/`value`, not MapBuilder defaults). + int32_to_int32_list_map: MapBuilder::new( + Some(MapFieldNames { + entry: "entries".to_string(), + key: "key".to_string(), + value: "value".to_string(), + }), + Int32Builder::new(), + ListBuilder::new(Int32Builder::new()), + ), + } + } + + pub(crate) fn add_string(&mut self, code: InfoCode, value: impl AsRef) { + self.info_name.append_value(u32::from(&code)); + self.type_id.push(Self::CODE_STRING); + self.offset.push(self.string_value.len() as i32); + self.string_value.append_value(value); + } + + pub(crate) fn add_bool(&mut self, code: InfoCode, value: bool) { + self.info_name.append_value(u32::from(&code)); + self.type_id.push(Self::CODE_BOOL); + self.offset.push(self.bool_value.len() as i32); + self.bool_value.append_value(value); + } + + pub(crate) fn add_i64(&mut self, code: InfoCode, value: i64) { + self.info_name.append_value(u32::from(&code)); + self.type_id.push(Self::CODE_INT64); + self.offset.push(self.int64_value.len() as i32); + self.int64_value.append_value(value); + } + + pub(crate) fn finish(mut self) -> Result> { + let num_rows = self.type_id.len(); + let info_name = self.info_name.finish(); + + let type_ids = ScalarBuffer::from(self.type_id); + let offsets = ScalarBuffer::from(self.offset); + + let children: Vec = vec![ + Arc::new(self.string_value.finish()), + Arc::new(self.bool_value.finish()), + Arc::new(self.int64_value.finish()), + Arc::new(self.int32_bitmask.finish()), + Arc::new(self.string_list.finish()), + Arc::new(self.int32_to_int32_list_map.finish()), + ]; + + let schema = GET_INFO_SCHEMA.clone(); + let DataType::Union(union_fields, UnionMode::Dense) = schema.field(1).data_type() else { + return Err(Error::with_message_and_status( + "GET_INFO_SCHEMA.info_value is not a dense union", + Status::Internal, + )); + }; + + let info_value = UnionArray::try_new( + union_fields.clone(), + type_ids, + Some(offsets), + children, + ) + .map_err(|e| { + Error::with_message_and_status( + format!("error building get_info union array: {e}"), + Status::Internal, + ) + })?; + + let batch = RecordBatch::try_new( + schema.clone(), + vec![Arc::new(info_name), Arc::new(info_value)], + ) + .map_err(|e| { + Error::with_message_and_status( + format!("error building get_info record batch: {e}"), + Status::Internal, + ) + })?; + + debug_assert_eq!(batch.num_rows(), num_rows); + + Ok(Box::new(RecordBatchIterator::new( + std::iter::once(Ok(batch)), + schema, + ))) + } +} + +/// Whether `codes` requests `code` (or requests everything when `None`). +#[inline] +pub(crate) fn wants(codes: Option<&HashSet>, code: InfoCode) -> bool { + codes.is_none_or(|set| set.contains(&code)) +} diff --git a/src/lib.rs b/src/lib.rs index d74e7f0..d8624f6 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -97,12 +97,14 @@ //! all strings as binary strings instead. This may be set at the connection or statement level. use crate::options::{OptionValueExt, ProductInfo}; use adbc_core::error::{Error, Status}; +use adbc_core::constants::ADBC_VERSION_1_1_0; use adbc_core::options::{InfoCode, ObjectDepth, OptionConnection, OptionDatabase, OptionValue}; use adbc_core::{Connection, Database, Driver, Optionable, schemas}; use arrow_array::{RecordBatchIterator, RecordBatchReader, record_batch}; use arrow_schema::Schema; use clickhouse::Client; use rand::distr::{Alphanumeric, SampleString}; +use std::future::Future; use std::collections::{HashMap, HashSet}; use std::ops::Deref; use std::sync::Arc; @@ -124,6 +126,7 @@ macro_rules! err_unimplemented { }; } +mod info; pub mod options; mod reader; mod schema; @@ -664,11 +667,17 @@ impl Connection for ClickhouseConnection { err_unimplemented!("ClickhouseConnection::cancel()") } + /// Return driver and vendor metadata as described by [`InfoCode`]. + /// + /// When `codes` is `None`, all supported info codes are returned. Unsupported codes + /// (currently `VendorArrowVersion` and Substrait version bounds) are omitted. + /// + /// `VendorVersion` is fetched from the server via `SELECT version()`. fn get_info( &self, - _codes: Option>, + codes: Option>, ) -> adbc_core::error::Result> { - err_unimplemented!("ClickhouseConnection::get_info()" -> Box) + self.tokio.block_on(self.build_info(codes.as_ref())) } fn get_objects( @@ -890,6 +899,72 @@ impl ClickhouseConnection { )), } } + + async fn build_info( + &self, + codes: Option<&HashSet>, + ) -> Result> { + let mut builder = info::InfoBuilder::new(); + + if info::wants(codes, InfoCode::VendorName) { + builder.add_string(InfoCode::VendorName, "ClickHouse"); + } + + if info::wants(codes, InfoCode::VendorVersion) { + let version = fetch_vendor_version(&self.client).await?; + builder.add_string(InfoCode::VendorVersion, version); + } + + // ClickHouse does not expose a vendor Arrow library version over HTTP. + // Omit `VendorArrowVersion` rather than guessing. + + if info::wants(codes, InfoCode::VendorSql) { + builder.add_bool(InfoCode::VendorSql, true); + } + + if info::wants(codes, InfoCode::VendorSubstrait) { + builder.add_bool(InfoCode::VendorSubstrait, false); + } + + // Substrait is unsupported. Arrow dense unions cannot carry top-level nulls, so we omit + // `VendorSubstrait{Min,Max}Version` rather than returning null `info_value` rows. + + if info::wants(codes, InfoCode::DriverName) { + builder.add_string(InfoCode::DriverName, "ADBC ClickHouse Driver"); + } + + if info::wants(codes, InfoCode::DriverVersion) { + builder.add_string(InfoCode::DriverVersion, env!("CARGO_PKG_VERSION")); + } + + // FIXME: populate `DriverArrowVersion` once we bump `arrow-*` far enough to use + // `arrow_array::ARROW_VERSION` (apache/arrow-rs#10957). + + if info::wants(codes, InfoCode::DriverAdbcVersion) { + builder.add_i64(InfoCode::DriverAdbcVersion, ADBC_VERSION_1_1_0 as i64); + } + + builder.finish() + } +} + +#[derive(clickhouse::Row, serde::Deserialize)] +struct VendorVersionRow { + version: String, +} + +async fn fetch_vendor_version(client: &Client) -> Result { + client + .query("SELECT version() AS version") + .fetch_one::() + .await + .map(|row| row.version) + .map_err(|e| { + Error::with_message_and_status( + format!("error fetching ClickHouse version: {e}"), + Status::IO, + ) + }) } /// Wrapper for [`Client`] that implements expected semantics for certain settings. diff --git a/tests/it/get_info.rs b/tests/it/get_info.rs new file mode 100644 index 0000000..9bdc7d6 --- /dev/null +++ b/tests/it/get_info.rs @@ -0,0 +1,146 @@ +use adbc_core::constants::{ + ADBC_INFO_DRIVER_ADBC_VERSION, ADBC_INFO_DRIVER_ARROW_VERSION, ADBC_INFO_DRIVER_NAME, + ADBC_INFO_DRIVER_VERSION, ADBC_INFO_VENDOR_NAME, ADBC_INFO_VENDOR_SQL, + ADBC_INFO_VENDOR_SUBSTRAIT, ADBC_INFO_VENDOR_VERSION, ADBC_VERSION_1_1_0, +}; +use adbc_core::options::InfoCode; +use adbc_core::schemas::GET_INFO_SCHEMA; +use adbc_core::{Connection, Database}; +use arrow_array::cast::AsArray; +use arrow_array::types::UInt32Type; +use arrow_array::{BooleanArray, Int64Array, StringArray, UnionArray}; +use std::collections::{HashMap, HashSet}; + +use crate::test_database; + +#[test] +fn get_info_all() { + let db = test_database(); + let conn = db.new_connection().unwrap(); + + let reader = conn.get_info(None).unwrap(); + assert_eq!(reader.schema().as_ref(), GET_INFO_SCHEMA.as_ref()); + + let batches = reader.collect::, _>>().unwrap(); + assert_eq!(batches.len(), 1); + let batch = &batches[0]; + + let names = batch.column(0).as_primitive::(); + let values = batch + .column(1) + .as_any() + .downcast_ref::() + .expect("info_value should be a UnionArray"); + + let mut by_code = HashMap::new(); + for i in 0..batch.num_rows() { + by_code.insert(names.value(i), i); + } + + assert_eq!( + string_value(values, by_code[&ADBC_INFO_VENDOR_NAME]), + "ClickHouse" + ); + + let vendor_version = string_value(values, by_code[&ADBC_INFO_VENDOR_VERSION]); + assert!( + !vendor_version.is_empty(), + "expected non-empty vendor version, got {vendor_version:?}" + ); + + assert!(bool_value(values, by_code[&ADBC_INFO_VENDOR_SQL])); + assert!(!bool_value(values, by_code[&ADBC_INFO_VENDOR_SUBSTRAIT])); + + assert_eq!( + string_value(values, by_code[&ADBC_INFO_DRIVER_NAME]), + "ADBC ClickHouse Driver" + ); + assert_eq!( + string_value(values, by_code[&ADBC_INFO_DRIVER_VERSION]), + env!("CARGO_PKG_VERSION") + ); + // FIXME: populate once arrow-* exposes a version constant (see get_info in lib.rs). + assert!( + !by_code.contains_key(&ADBC_INFO_DRIVER_ARROW_VERSION), + "DriverArrowVersion should be omitted until arrow-* provides ARROW_VERSION" + ); + assert_eq!( + i64_value(values, by_code[&ADBC_INFO_DRIVER_ADBC_VERSION]), + ADBC_VERSION_1_1_0 as i64 + ); +} + +#[test] +fn get_info_filtered() { + let db = test_database(); + let conn = db.new_connection().unwrap(); + + let reader = conn + .get_info(Some(HashSet::from([ + InfoCode::DriverName, + InfoCode::VendorSql, + ]))) + .unwrap(); + + let batches = reader.collect::, _>>().unwrap(); + let batch = &batches[0]; + assert_eq!(batch.num_rows(), 2); + + let names = batch.column(0).as_primitive::(); + let values = batch + .column(1) + .as_any() + .downcast_ref::() + .expect("info_value should be a UnionArray"); + + let mut codes = Vec::new(); + for i in 0..batch.num_rows() { + codes.push(names.value(i)); + match names.value(i) { + ADBC_INFO_DRIVER_NAME => { + assert_eq!(string_value(values, i), "ADBC ClickHouse Driver"); + } + ADBC_INFO_VENDOR_SQL => { + assert!(bool_value(values, i)); + } + other => panic!("unexpected info code {other}"), + } + } + + codes.sort_unstable(); + assert_eq!( + codes, + vec![ADBC_INFO_VENDOR_SQL, ADBC_INFO_DRIVER_NAME] + ); +} + +fn string_value(values: &UnionArray, row: usize) -> String { + assert_eq!(values.type_id(row), 0, "expected string_value type id"); + values + .value(row) + .as_any() + .downcast_ref::() + .expect("string child") + .value(0) + .to_string() +} + +fn bool_value(values: &UnionArray, row: usize) -> bool { + assert_eq!(values.type_id(row), 1, "expected bool_value type id"); + values + .value(row) + .as_any() + .downcast_ref::() + .expect("bool child") + .value(0) +} + +fn i64_value(values: &UnionArray, row: usize) -> i64 { + assert_eq!(values.type_id(row), 2, "expected int64_value type id"); + values + .value(row) + .as_any() + .downcast_ref::() + .expect("int64 child") + .value(0) +} diff --git a/tests/it/main.rs b/tests/it/main.rs index 9f6c5c6..6304320 100644 --- a/tests/it/main.rs +++ b/tests/it/main.rs @@ -12,6 +12,7 @@ use arrow_schema::{DataType, Field, Schema, TimeUnit}; use std::sync::Arc; mod bulk_ingest; +mod get_info; mod database; mod get_table_schema; mod params; diff --git a/tests/it/params.rs b/tests/it/params.rs index 93d9e72..4251877 100644 --- a/tests/it/params.rs +++ b/tests/it/params.rs @@ -10,6 +10,10 @@ use uuid::Uuid; fn binary_strings_round_trip() { let params_schema = Arc::new(Schema::new(vec![ Field::new("field_uuid", DataType::FixedSizeBinary(16), false) + // Match the canonical extension metadata ClickHouse returns. + // Do not include server-version-specific keys such as + // `PARQUET:logical_type`. + // // `.with_extension_type(arrow_schema::extensions::Uuid)` // deletes the `ARROW:extension:metadata` key so equality wouldn't work. .with_metadata(