@lix-js/sdk 0.6.0-preview.0 → 0.6.0-preview.2

package/dist-engine-src/src/sql2/mod.rs

@@ -0,0 +1,43 @@
+mod change_provider;
+mod classify;
+mod commit_derived_provider;
+mod context;
+mod directory_history_provider;
+mod directory_provider;
+mod dml;
+mod entity_history_provider;
+mod entity_provider;
+mod error;
+mod execute;
+mod file_history_provider;
+mod file_provider;
+mod filesystem_planner;
+mod filesystem_predicates;
+mod filesystem_visibility;
+mod history_projection;
+mod history_provider;
+mod history_route;
+mod lix_state_provider;
+mod read_only;
+mod record_batch;
+mod result_metadata;
+mod runtime;
+mod session;
+mod udfs;
+mod version_provider;
+mod version_scope;
+mod write_normalization;
+
+pub(crate) use classify::{
+    classify_statement, dml_target_table_names, validate_supported_statement_ast, SqlStatementKind,
+};
+pub(crate) use context::{
+    ChangelogQuerySource, SqlChangelogQuerySource, SqlExecutionContext, SqlJsonReader,
+    SqlWriteContext, SqlWriteExecutionContext, WriteAccess, WriteContextLiveStateReader,
+    WriteContextVersionRefReader,
+};
+#[allow(unused_imports)]
+pub(crate) use execute::{
+    create_logical_plan, create_write_logical_plan, execute_logical_plan, execute_sql,
+    SqlLogicalPlan,
+};

package/dist-engine-src/src/sql2/read_only.rs

@@ -0,0 +1,65 @@
+use datafusion::error::DataFusionError;
+
+use crate::transaction::types::StageRow;
+use crate::LixError;
+
+pub(crate) fn reject_read_only_entity_surface(
+    schema_key: &str,
+    operation: &str,
+) -> Result<(), DataFusionError> {
+    if schema_key == "lix_directory_descriptor" {
+        return Err(read_only_error(
+            operation,
+            schema_key,
+            "Use the writable lix_directory surface to create, update, or delete directories.",
+        ));
+    }
+    if let Some(message) = read_only_schema_message(schema_key) {
+        return Err(read_only_error(operation, schema_key, message));
+    }
+    Ok(())
+}
+
+pub(crate) fn reject_read_only_stage_rows(
+    rows: &[StageRow],
+    operation: &str,
+) -> Result<(), DataFusionError> {
+    for row in rows {
+        if let Some(message) = read_only_schema_message(&row.schema_key) {
+            return Err(read_only_error(operation, &row.schema_key, message));
+        }
+    }
+    Ok(())
+}
+
+fn read_only_error(operation: &str, schema_key: &str, message: &'static str) -> DataFusionError {
+    super::error::lix_error_to_datafusion_error(
+        LixError::new(
+            LixError::CODE_READ_ONLY,
+            format!("{operation} cannot write read-only surface '{schema_key}'"),
+        )
+        .with_hint(message),
+    )
+}
+
+fn read_only_schema_message(schema_key: &str) -> Option<&'static str> {
+    match schema_key {
+        "lix_version_descriptor" | "lix_version_ref" => {
+            Some("Use the writable lix_version surface to create, update, or delete versions.")
+        }
+        "lix_file_descriptor" => {
+            Some("Use the writable lix_file surface to create, update, or delete files.")
+        }
+        "lix_binary_blob_ref" => {
+            Some("Use the writable lix_file data column to create, update, or delete file contents.")
+        }
+        "lix_commit"
+        | "lix_commit_edge"
+        | "lix_change"
+        | "lix_change_set"
+        | "lix_change_set_element" => Some(
+            "Commit graph and changelog surfaces are read-only; Lix creates them when transactions commit.",
+        ),
+        _ => None,
+    }
+}

package/dist-engine-src/src/sql2/record_batch.rs

@@ -0,0 +1,17 @@
+use datafusion::arrow::array::ArrayRef;
+use datafusion::arrow::datatypes::SchemaRef;
+use datafusion::arrow::record_batch::{RecordBatch, RecordBatchOptions};
+use datafusion::common::{DataFusionError, Result};
+
+pub(crate) fn record_batch_with_row_count(
+    schema: SchemaRef,
+    columns: Vec<ArrayRef>,
+    row_count: usize,
+) -> Result<RecordBatch> {
+    if schema.fields().is_empty() {
+        let options = RecordBatchOptions::new().with_row_count(Some(row_count));
+        return RecordBatch::try_new_with_options(schema, columns, &options)
+            .map_err(DataFusionError::from);
+    }
+    RecordBatch::try_new(schema, columns).map_err(DataFusionError::from)
+}

package/dist-engine-src/src/sql2/result_metadata.rs

@@ -0,0 +1,29 @@
+use std::collections::HashMap;
+
+use datafusion::arrow::datatypes::Field;
+
+pub(crate) const LIX_VALUE_TYPE_METADATA_KEY: &str = "lix.value_type";
+pub(crate) const LIX_VALUE_TYPE_JSON: &str = "json";
+
+pub(crate) fn json_field(name: impl Into<String>, nullable: bool) -> Field {
+    Field::new(name, datafusion::arrow::datatypes::DataType::Utf8, nullable)
+        .with_metadata(json_field_metadata_map())
+}
+
+pub(crate) fn mark_json_field(field: Field) -> Field {
+    field.with_metadata(json_field_metadata_map())
+}
+
+pub(crate) fn field_is_json(field: &Field) -> bool {
+    field
+        .metadata()
+        .get(LIX_VALUE_TYPE_METADATA_KEY)
+        .is_some_and(|value| value == LIX_VALUE_TYPE_JSON)
+}
+
+fn json_field_metadata_map() -> HashMap<String, String> {
+    HashMap::from([(
+        LIX_VALUE_TYPE_METADATA_KEY.to_string(),
+        LIX_VALUE_TYPE_JSON.to_string(),
+    )])
+}

package/dist-engine-src/src/sql2/runtime.rs

@@ -0,0 +1,60 @@
+use std::sync::Arc;
+
+use datafusion::arrow::record_batch::RecordBatch;
+use datafusion::dataframe::DataFrame;
+use datafusion::error::Result;
+use datafusion::execution::TaskContext;
+use datafusion::physical_plan::{ExecutionPlan, ExecutionPlanProperties};
+use futures_util::TryStreamExt;
+
+pub(crate) async fn collect_dataframe(dataframe: DataFrame) -> Result<Vec<RecordBatch>> {
+    let task_ctx = Arc::new(dataframe.task_ctx());
+    let plan = dataframe.create_physical_plan().await?;
+    collect_input_plan(plan, task_ctx).await
+}
+
+pub(crate) async fn collect_input_plan(
+    plan: Arc<dyn ExecutionPlan>,
+    task_ctx: Arc<TaskContext>,
+) -> Result<Vec<RecordBatch>> {
+    validate_physical_plan(&plan)?;
+    let partition_count = plan.output_partitioning().partition_count();
+    let mut batches = Vec::new();
+    for partition in 0..partition_count {
+        let partition_batches = plan
+            .execute(partition, Arc::clone(&task_ctx))?
+            .try_collect::<Vec<_>>()
+            .await?;
+        batches.extend(partition_batches);
+    }
+    Ok(batches)
+}
+
+#[cfg(not(target_arch = "wasm32"))]
+fn validate_physical_plan(_plan: &Arc<dyn ExecutionPlan>) -> Result<()> {
+    Ok(())
+}
+
+#[cfg(target_arch = "wasm32")]
+fn validate_physical_plan(plan: &Arc<dyn ExecutionPlan>) -> Result<()> {
+    let operator_name = plan.name();
+    if is_wasm_unsafe_operator(operator_name) {
+        return Err(datafusion::error::DataFusionError::Plan(format!(
+            "SQL physical operator '{operator_name}' is not supported by the WebAssembly runtime yet"
+        )));
+    }
+
+    for child in plan.children() {
+        validate_physical_plan(child)?;
+    }
+
+    Ok(())
+}
+
+#[cfg(target_arch = "wasm32")]
+fn is_wasm_unsafe_operator(operator_name: &str) -> bool {
+    matches!(
+        operator_name,
+        "CoalescePartitionsExec" | "RepartitionExec" | "SortPreservingMergeExec"
+    )
+}

package/dist-engine-src/src/sql2/session.rs

@@ -0,0 +1,135 @@
+use std::sync::Arc;
+
+use datafusion::prelude::{SessionConfig, SessionContext};
+
+use crate::LixError;
+
+use super::change_provider::register_lix_change_provider;
+use super::commit_derived_provider::register_commit_derived_providers;
+use super::directory_history_provider::register_lix_directory_history_provider;
+use super::directory_provider::{
+    register_lix_directory_providers, register_lix_directory_write_providers,
+};
+use super::entity_provider::{register_entity_providers, register_entity_write_providers};
+use super::file_history_provider::register_lix_file_history_provider;
+use super::file_provider::{register_lix_file_providers, register_lix_file_write_providers};
+use super::history_provider::register_history_providers;
+use super::lix_state_provider::{register_lix_state_providers, register_lix_state_write_providers};
+use super::udfs::register_sql2_functions;
+use super::version_provider::{register_lix_version_provider, register_lix_version_write_provider};
+use super::{SqlExecutionContext, SqlWriteContext, SqlWriteExecutionContext};
+
+pub(crate) async fn build_read_session(
+    ctx: &dyn SqlExecutionContext,
+) -> Result<SessionContext, LixError> {
+    let session = new_sql_session_context();
+    let version_ref = ctx.version_ref();
+    let active_version_commit_id = version_ref
+        .load_head(ctx.active_version_id())
+        .await?
+        .map(|head| head.commit_id);
+    register_sql2_functions(&session, ctx.functions(), active_version_commit_id);
+    register_lix_state_providers(
+        &session,
+        ctx.active_version_id(),
+        ctx.live_state(),
+        Arc::clone(&version_ref),
+    )
+    .await?;
+    register_lix_version_provider(&session, ctx.live_state(), Arc::clone(&version_ref)).await?;
+    let changelog_query_source = ctx.changelog_query_source();
+    register_lix_change_provider(&session, changelog_query_source.clone()).await?;
+    let commit_graph = ctx.commit_graph();
+    register_commit_derived_providers(&session, commit_graph, Arc::clone(&version_ref)).await?;
+    let state_history_commit_graph = ctx.commit_graph();
+    register_history_providers(
+        &session,
+        state_history_commit_graph,
+        changelog_query_source.clone(),
+    )
+    .await?;
+    let file_history_commit_graph = ctx.commit_graph();
+    register_lix_file_history_provider(
+        &session,
+        file_history_commit_graph,
+        changelog_query_source.clone(),
+        ctx.blob_reader(),
+    )
+    .await?;
+    let directory_history_commit_graph = ctx.commit_graph();
+    register_lix_directory_history_provider(
+        &session,
+        directory_history_commit_graph,
+        changelog_query_source.clone(),
+    )
+    .await?;
+    let entity_commit_graph = Arc::new(tokio::sync::Mutex::new(ctx.commit_graph()));
+    register_lix_directory_providers(
+        &session,
+        ctx.active_version_id(),
+        ctx.live_state(),
+        Arc::clone(&version_ref),
+        ctx.functions(),
+    )
+    .await?;
+    register_lix_file_providers(
+        &session,
+        ctx.active_version_id(),
+        ctx.live_state(),
+        Arc::clone(&version_ref),
+        ctx.blob_reader(),
+        ctx.functions(),
+    )
+    .await?;
+    register_entity_providers(
+        &session,
+        ctx.active_version_id(),
+        ctx.live_state(),
+        Arc::clone(&version_ref),
+        entity_commit_graph,
+        changelog_query_source,
+        &ctx.list_visible_schemas()?,
+    )
+    .await?;
+
+    Ok(session)
+}
+
+pub(crate) async fn build_write_session(
+    ctx: &mut dyn SqlWriteExecutionContext,
+) -> Result<SessionContext, LixError> {
+    let session = new_sql_session_context();
+    let write_ctx = SqlWriteContext::new(ctx);
+    let active_version_commit_id = write_ctx
+        .load_version_head(&write_ctx.active_version_id())
+        .await?;
+    register_sql2_functions(&session, write_ctx.functions(), active_version_commit_id);
+
+    register_lix_state_write_providers(&session, write_ctx.clone()).await?;
+    register_lix_version_write_provider(&session, write_ctx.clone()).await?;
+
+    register_lix_directory_write_providers(&session, write_ctx.clone()).await?;
+    register_lix_file_write_providers(&session, write_ctx.clone()).await?;
+    register_entity_write_providers(
+        &session,
+        write_ctx.clone(),
+        &write_ctx.list_visible_schemas()?,
+    )
+    .await?;
+
+    Ok(session)
+}
+
+fn new_sql_session_context() -> SessionContext {
+    SessionContext::new_with_config(
+        SessionConfig::new()
+            .with_information_schema(true)
+            .with_target_partitions(1)
+            .set_bool("datafusion.optimizer.repartition_aggregations", false)
+            .set_bool("datafusion.optimizer.repartition_joins", false)
+            .set_bool("datafusion.optimizer.repartition_sorts", false)
+            .set_bool("datafusion.optimizer.repartition_windows", false)
+            .set_bool("datafusion.optimizer.repartition_file_scans", false)
+            .set_bool("datafusion.optimizer.enable_round_robin_repartition", false),
+    )
+}

package/dist-engine-src/src/sql2/udfs/common.rs

@@ -0,0 +1,295 @@
+use std::sync::Arc;
+
+use datafusion::arrow::array::{
+    Array, ArrayRef, BinaryArray, BooleanArray, Float32Array, Float64Array, Int16Array, Int32Array,
+    Int64Array, Int8Array, LargeBinaryArray, LargeStringArray, StringArray, UInt16Array,
+    UInt32Array, UInt64Array, UInt8Array,
+};
+use datafusion::common::{plan_err, DataFusionError, Result};
+use datafusion::logical_expr::ColumnarValue;
+use serde_json::Value as JsonValue;
+
+pub(super) fn scalar_inputs(args: &[ColumnarValue]) -> bool {
+    args.iter()
+        .all(|value| matches!(value, ColumnarValue::Scalar(_)))
+}
+
+pub(super) fn json_value_to_serde(array: &dyn Array, row: usize) -> Result<Option<JsonValue>> {
+    let Some(raw) = text_like_value(array, row)? else {
+        return Ok(None);
+    };
+    serde_json::from_str::<JsonValue>(&raw)
+        .map(Some)
+        .map_err(|error| {
+            DataFusionError::Execution(format!(
+                "JSON function expected valid JSON text in its first argument, got error: {error}"
+            ))
+        })
+}
+
+pub(super) fn text_like_value(array: &dyn Array, row: usize) -> Result<Option<String>> {
+    if let Some(array) = array.as_any().downcast_ref::<StringArray>() {
+        return Ok((!array.is_null(row)).then(|| array.value(row).to_string()));
+    }
+    if let Some(array) = array.as_any().downcast_ref::<LargeStringArray>() {
+        return Ok((!array.is_null(row)).then(|| array.value(row).to_string()));
+    }
+    if let Some(value) = numeric_value(array, row)? {
+        return Ok(Some(value));
+    }
+    if let Some(array) = array.as_any().downcast_ref::<BooleanArray>() {
+        return Ok((!array.is_null(row)).then(|| {
+            if array.value(row) {
+                "true".to_string()
+            } else {
+                "false".to_string()
+            }
+        }));
+    }
+    if let Some(array) = array.as_any().downcast_ref::<BinaryArray>() {
+        return Ok(
+            (!array.is_null(row)).then(|| String::from_utf8_lossy(array.value(row)).to_string())
+        );
+    }
+    if let Some(array) = array.as_any().downcast_ref::<LargeBinaryArray>() {
+        return Ok(
+            (!array.is_null(row)).then(|| String::from_utf8_lossy(array.value(row)).to_string())
+        );
+    }
+    Err(DataFusionError::Execution(format!(
+        "unsupported argument type for JSON/text function: {:?}",
+        array.data_type()
+    )))
+}
+
+pub(super) fn numeric_value(array: &dyn Array, row: usize) -> Result<Option<String>> {
+    macro_rules! numeric_array {
+        ($ty:ty) => {
+            if let Some(array) = array.as_any().downcast_ref::<$ty>() {
+                return Ok((!array.is_null(row)).then(|| array.value(row).to_string()));
+            }
+        };
+    }
+
+    numeric_array!(Int8Array);
+    numeric_array!(Int16Array);
+    numeric_array!(Int32Array);
+    numeric_array!(Int64Array);
+    numeric_array!(UInt8Array);
+    numeric_array!(UInt16Array);
+    numeric_array!(UInt32Array);
+    numeric_array!(UInt64Array);
+    numeric_array!(Float32Array);
+    numeric_array!(Float64Array);
+    Ok(None)
+}
+
+pub(super) fn decode_utf8_value(array: &dyn Array, row: usize) -> Result<Option<String>> {
+    if let Some(array) = array.as_any().downcast_ref::<BinaryArray>() {
+        return (!array.is_null(row))
+            .then(|| String::from_utf8(array.value(row).to_vec()))
+            .transpose()
+            .map_err(|error| {
+                DataFusionError::Execution(format!(
+                    "lix_text_decode() expected valid UTF8 bytes: {error}"
+                ))
+            });
+    }
+    if let Some(array) = array.as_any().downcast_ref::<LargeBinaryArray>() {
+        return (!array.is_null(row))
+            .then(|| String::from_utf8(array.value(row).to_vec()))
+            .transpose()
+            .map_err(|error| {
+                DataFusionError::Execution(format!(
+                    "lix_text_decode() expected valid UTF8 bytes: {error}"
+                ))
+            });
+    }
+    if let Some(array) = array.as_any().downcast_ref::<StringArray>() {
+        return Ok((!array.is_null(row)).then(|| array.value(row).to_string()));
+    }
+    if let Some(array) = array.as_any().downcast_ref::<LargeStringArray>() {
+        return Ok((!array.is_null(row)).then(|| array.value(row).to_string()));
+    }
+    Err(DataFusionError::Execution(format!(
+        "lix_text_decode() expected Binary or Utf8, got {:?}",
+        array.data_type()
+    )))
+}
+
+pub(super) fn encode_utf8_value(array: &dyn Array, row: usize) -> Result<Option<Vec<u8>>> {
+    if let Some(array) = array.as_any().downcast_ref::<StringArray>() {
+        return Ok((!array.is_null(row)).then(|| array.value(row).as_bytes().to_vec()));
+    }
+    if let Some(array) = array.as_any().downcast_ref::<LargeStringArray>() {
+        return Ok((!array.is_null(row)).then(|| array.value(row).as_bytes().to_vec()));
+    }
+    if let Some(array) = array.as_any().downcast_ref::<BinaryArray>() {
+        return Ok((!array.is_null(row)).then(|| array.value(row).to_vec()));
+    }
+    if let Some(array) = array.as_any().downcast_ref::<LargeBinaryArray>() {
+        return Ok((!array.is_null(row)).then(|| array.value(row).to_vec()));
+    }
+    Err(DataFusionError::Execution(format!(
+        "lix_text_encode() expected Utf8 or Binary, got {:?}",
+        array.data_type()
+    )))
+}
+
+pub(super) fn validate_utf8_encoding_arg(
+    fn_name: &str,
+    encoding: Option<&ColumnarValue>,
+) -> Result<()> {
+    let Some(encoding) = encoding else {
+        return Ok(());
+    };
+    let arrays = ColumnarValue::values_to_arrays(std::slice::from_ref(encoding))?;
+    let array = &arrays[0];
+    if array.len() == 0 {
+        return Ok(());
+    }
+    let Some(value) = text_like_value(array.as_ref(), 0)? else {
+        return Ok(());
+    };
+    let normalized = value.trim().to_ascii_uppercase().replace('-', "");
+    if normalized == "UTF8" {
+        Ok(())
+    } else {
+        plan_err!("{fn_name}() only supports UTF8 encoding, got '{value}'")
+    }
+}
+
+pub(super) fn extract_json_path(
+    fn_name: &str,
+    arrays: &[ArrayRef],
+    row: usize,
+) -> Result<Option<JsonValue>> {
+    let Some(mut current) = json_value_to_serde(arrays[0].as_ref(), row)? else {
+        return Ok(None);
+    };
+
+    for path in &arrays[1..] {
+        let Some(segment) = json_path_segment(fn_name, path.as_ref(), row)? else {
+            return Ok(None);
+        };
+        let next = match segment {
+            JsonPathSegment::Key(key) => current.get(&key).cloned(),
+            JsonPathSegment::Index(index) => current
+                .as_array()
+                .and_then(|values| values.get(index))
+                .cloned(),
+        };
+        let Some(value) = next else {
+            return Ok(None);
+        };
+        current = value;
+    }
+
+    Ok(Some(current))
+}
+
+pub(super) fn json_text_value(value: &JsonValue) -> Result<String> {
+    match value {
+        JsonValue::String(text) => Ok(text.clone()),
+        JsonValue::Number(number) => Ok(number.to_string()),
+        JsonValue::Bool(boolean) => Ok(if *boolean {
+            "true".to_string()
+        } else {
+            "false".to_string()
+        }),
+        JsonValue::Array(_) | JsonValue::Object(_) => {
+            serde_json::to_string(value).map_err(|error| {
+                DataFusionError::Execution(format!(
+                    "lix_json_get_text() could not render JSON value: {error}"
+                ))
+            })
+        }
+        JsonValue::Null => Ok("null".to_string()),
+    }
+}
+
+pub(super) fn json_json_value(value: &JsonValue) -> Result<String> {
+    serde_json::to_string(value).map_err(|error| {
+        DataFusionError::Execution(format!(
+            "lix_json_get() could not render JSON value: {error}"
+        ))
+    })
+}
+
+enum JsonPathSegment {
+    Key(String),
+    Index(usize),
+}
+
+fn json_path_segment(
+    fn_name: &str,
+    array: &dyn Array,
+    row: usize,
+) -> Result<Option<JsonPathSegment>> {
+    if let Some(array) = array.as_any().downcast_ref::<StringArray>() {
+        if array.is_null(row) {
+            return Ok(None);
+        }
+        let value = array.value(row).to_string();
+        validate_json_path_key_segment(fn_name, &value)?;
+        return Ok(Some(JsonPathSegment::Key(value)));
+    }
+    if let Some(array) = array.as_any().downcast_ref::<LargeStringArray>() {
+        if array.is_null(row) {
+            return Ok(None);
+        }
+        let value = array.value(row).to_string();
+        validate_json_path_key_segment(fn_name, &value)?;
+        return Ok(Some(JsonPathSegment::Key(value)));
+    }
+    macro_rules! index_array {
+        ($ty:ty) => {
+            if let Some(array) = array.as_any().downcast_ref::<$ty>() {
+                if array.is_null(row) {
+                    return Ok(None);
+                }
+                let value = array.value(row);
+                let index = usize::try_from(value).map_err(|_| {
+                    DataFusionError::Execution(format!(
+                        "{fn_name}() path indexes must be non-negative integers"
+                    ))
+                })?;
+                return Ok(Some(JsonPathSegment::Index(index)));
+            }
+        };
+    }
+    index_array!(UInt8Array);
+    index_array!(UInt16Array);
+    index_array!(UInt32Array);
+    index_array!(UInt64Array);
+    index_array!(Int8Array);
+    index_array!(Int16Array);
+    index_array!(Int32Array);
+    index_array!(Int64Array);
+    Err(DataFusionError::Execution(format!(
+        "{fn_name}() path arguments must be strings or non-negative integers, got {:?}",
+        array.data_type()
+    )))
+}
+
+fn validate_json_path_key_segment(fn_name: &str, value: &str) -> Result<()> {
+    if value == "$" || value.starts_with("$.") || value.starts_with("$[") || value.starts_with('/')
+    {
+        return Err(DataFusionError::Execution(format!(
+            "{fn_name}() uses variadic path segments, not JSONPath or JSON Pointer; got '{value}'"
+        )));
+    }
+    Ok(())
+}
+
+pub(super) fn binary_array_from_owned(values: &[Option<Vec<u8>>]) -> BinaryArray {
+    let refs = values
+        .iter()
+        .map(|value| value.as_deref())
+        .collect::<Vec<_>>();
+    BinaryArray::from(refs)
+}
+
+pub(super) fn array_ref<T: Array + 'static>(array: T) -> ArrayRef {
+    Arc::new(array)
+}

package/dist-engine-src/src/sql2/udfs/lix_active_version_commit_id.rs

@@ -0,0 +1,53 @@
+use std::any::Any;
+
+use datafusion::arrow::datatypes::DataType;
+use datafusion::common::{plan_err, Result, ScalarValue};
+use datafusion::logical_expr::{
+    ColumnarValue, ScalarFunctionArgs, ScalarUDFImpl, Signature, Volatility,
+};
+
+#[derive(Clone, PartialEq, Eq, Hash)]
+pub(super) struct LixActiveVersionCommitId {
+    commit_id: Option<String>,
+}
+
+impl LixActiveVersionCommitId {
+    pub(super) fn new(commit_id: Option<String>) -> Self {
+        Self { commit_id }
+    }
+}
+
+impl std::fmt::Debug for LixActiveVersionCommitId {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("LixActiveVersionCommitId").finish()
+    }
+}
+
+impl ScalarUDFImpl for LixActiveVersionCommitId {
+    fn as_any(&self) -> &dyn Any {
+        self
+    }
+
+    fn name(&self) -> &str {
+        "lix_active_version_commit_id"
+    }
+
+    fn signature(&self) -> &Signature {
+        static SIGNATURE: std::sync::LazyLock<Signature> =
+            std::sync::LazyLock::new(|| Signature::nullary(Volatility::Stable));
+        &SIGNATURE
+    }
+
+    fn return_type(&self, _arg_types: &[DataType]) -> Result<DataType> {
+        Ok(DataType::Utf8)
+    }
+
+    fn invoke_with_args(&self, args: ScalarFunctionArgs) -> Result<ColumnarValue> {
+        if !args.args.is_empty() {
+            return plan_err!("lix_active_version_commit_id requires no arguments");
+        }
+        Ok(ColumnarValue::Scalar(ScalarValue::Utf8(
+            self.commit_id.clone(),
+        )))
+    }
+}