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

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

@@ -0,0 +1,47 @@
+use std::any::Any;
+
+use datafusion::arrow::datatypes::DataType;
+use datafusion::common::{Result, ScalarValue};
+use datafusion::logical_expr::{
+    ColumnarValue, ScalarFunctionArgs, ScalarUDFImpl, Signature, Volatility,
+};
+
+#[derive(Debug, Clone, PartialEq, Eq, Hash)]
+pub(super) struct LixEmptyBlob;
+
+impl ScalarUDFImpl for LixEmptyBlob {
+    fn as_any(&self) -> &dyn Any {
+        self
+    }
+
+    fn name(&self) -> &str {
+        "lix_empty_blob"
+    }
+
+    fn signature(&self) -> &Signature {
+        static SIGNATURE: std::sync::LazyLock<Signature> =
+            std::sync::LazyLock::new(|| Signature::nullary(Volatility::Immutable));
+        &SIGNATURE
+    }
+
+    fn return_type(&self, _arg_types: &[DataType]) -> Result<DataType> {
+        Ok(DataType::Binary)
+    }
+
+    fn invoke_with_args(&self, _args: ScalarFunctionArgs) -> Result<ColumnarValue> {
+        Ok(ColumnarValue::Scalar(ScalarValue::Binary(Some(Vec::new()))))
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::super::test_support::single_binary;
+
+    #[tokio::test]
+    async fn returns_empty_binary_value() {
+        assert_eq!(
+            single_binary("SELECT lix_empty_blob()").await,
+            Some(Vec::new())
+        );
+    }
+}

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

@@ -0,0 +1,100 @@
+use std::any::Any;
+use std::sync::Arc;
+
+use datafusion::arrow::array::{Array, StringArray};
+use datafusion::arrow::datatypes::{DataType, FieldRef};
+use datafusion::common::{plan_err, DataFusionError, Result, ScalarValue};
+use datafusion::logical_expr::{
+    ColumnarValue, ReturnFieldArgs, ScalarFunctionArgs, ScalarUDFImpl, Signature, Volatility,
+};
+use serde_json::Value as JsonValue;
+
+use crate::sql2::result_metadata::json_field;
+
+use super::common::{scalar_inputs, text_like_value};
+
+#[derive(Debug, Clone, PartialEq, Eq, Hash)]
+pub(super) struct LixJson;
+
+impl ScalarUDFImpl for LixJson {
+    fn as_any(&self) -> &dyn Any {
+        self
+    }
+
+    fn name(&self) -> &str {
+        "lix_json"
+    }
+
+    fn signature(&self) -> &Signature {
+        static SIGNATURE: std::sync::LazyLock<Signature> =
+            std::sync::LazyLock::new(|| Signature::any(1, Volatility::Immutable));
+        &SIGNATURE
+    }
+
+    fn return_type(&self, _arg_types: &[DataType]) -> Result<DataType> {
+        Ok(DataType::Utf8)
+    }
+
+    fn return_field_from_args(&self, _args: ReturnFieldArgs) -> Result<FieldRef> {
+        Ok(Arc::new(json_field(self.name(), true)))
+    }
+
+    fn invoke_with_args(&self, args: ScalarFunctionArgs) -> Result<ColumnarValue> {
+        if args.args.len() != 1 {
+            return plan_err!("lix_json requires exactly 1 argument");
+        }
+        let scalar_inputs = scalar_inputs(&args.args);
+        let arrays = ColumnarValue::values_to_arrays(&args.args)?;
+        let input = &arrays[0];
+        let len = input.len();
+        let mut values = Vec::with_capacity(len);
+        for row in 0..len {
+            values.push(json_value(input.as_ref(), row)?);
+        }
+        if scalar_inputs {
+            Ok(ColumnarValue::Scalar(ScalarValue::Utf8(
+                values.into_iter().next().flatten(),
+            )))
+        } else {
+            Ok(ColumnarValue::Array(Arc::new(StringArray::from(values))))
+        }
+    }
+}
+
+fn json_value(array: &dyn Array, row: usize) -> Result<Option<String>> {
+    if matches!(array.data_type(), DataType::Null) {
+        return Ok(Some("null".to_string()));
+    }
+    let Some(raw) = text_like_value(array, row)? else {
+        return Ok(Some("null".to_string()));
+    };
+    let parsed = serde_json::from_str::<JsonValue>(&raw).map_err(|error| {
+        DataFusionError::Execution(format!(
+            "lix_json() expected valid JSON text, got error: {error}"
+        ))
+    })?;
+    Ok(Some(serde_json::to_string(&parsed).map_err(|error| {
+        DataFusionError::Execution(format!("lix_json() could not render JSON: {error}"))
+    })?))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::super::test_support::single_text;
+
+    #[tokio::test]
+    async fn canonicalizes_json_text() {
+        assert_eq!(
+            single_text("SELECT lix_json('{ \"name\" : \"Ada\" }')").await,
+            Some("{\"name\":\"Ada\"}".to_string())
+        );
+    }
+
+    #[tokio::test]
+    async fn null_input_returns_json_null() {
+        assert_eq!(
+            single_text("SELECT lix_json(NULL)").await,
+            Some("null".to_string())
+        );
+    }
+}

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

@@ -0,0 +1,99 @@
+use std::any::Any;
+use std::sync::Arc;
+
+use datafusion::arrow::array::StringArray;
+use datafusion::arrow::datatypes::{DataType, FieldRef};
+use datafusion::common::{plan_err, Result, ScalarValue};
+use datafusion::logical_expr::{
+    ColumnarValue, ReturnFieldArgs, ScalarFunctionArgs, ScalarUDFImpl, Signature, Volatility,
+};
+use serde_json::Value as JsonValue;
+
+use crate::sql2::result_metadata::json_field;
+
+use super::common::{extract_json_path, json_json_value, scalar_inputs};
+
+#[derive(Debug, Clone, PartialEq, Eq, Hash)]
+pub(super) struct LixJsonGet {
+    signature: Signature,
+}
+
+impl LixJsonGet {
+    pub(super) fn new() -> Self {
+        Self {
+            signature: Signature::variadic_any(Volatility::Immutable),
+        }
+    }
+}
+
+impl ScalarUDFImpl for LixJsonGet {
+    fn as_any(&self) -> &dyn Any {
+        self
+    }
+
+    fn name(&self) -> &str {
+        "lix_json_get"
+    }
+
+    fn signature(&self) -> &Signature {
+        &self.signature
+    }
+
+    fn return_type(&self, _arg_types: &[DataType]) -> Result<DataType> {
+        Ok(DataType::Utf8)
+    }
+
+    fn return_field_from_args(&self, _args: ReturnFieldArgs) -> Result<FieldRef> {
+        Ok(Arc::new(json_field(self.name(), true)))
+    }
+
+    fn invoke_with_args(&self, args: ScalarFunctionArgs) -> Result<ColumnarValue> {
+        if args.args.len() < 2 {
+            return plan_err!("lix_json_get requires at least 2 arguments");
+        }
+
+        let scalar_inputs = scalar_inputs(&args.args);
+        let arrays = ColumnarValue::values_to_arrays(&args.args)?;
+        let len = arrays.first().map(|array| array.len()).unwrap_or(1);
+
+        let mut values = Vec::with_capacity(len);
+        for row in 0..len {
+            values.push(match extract_json_path(self.name(), &arrays, row)? {
+                None | Some(JsonValue::Null) => None,
+                Some(other) => Some(json_json_value(&other)?),
+            });
+        }
+        if scalar_inputs {
+            Ok(ColumnarValue::Scalar(ScalarValue::Utf8(
+                values.into_iter().next().flatten(),
+            )))
+        } else {
+            Ok(ColumnarValue::Array(Arc::new(StringArray::from(values))))
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::super::test_support::single_text;
+
+    #[tokio::test]
+    async fn returns_json_representation() {
+        assert_eq!(
+            single_text("SELECT lix_json_get('{\"name\":\"Ada\"}', 'name')").await,
+            Some("\"Ada\"".to_string())
+        );
+        assert_eq!(
+            single_text("SELECT lix_json_get('{\"tags\":[\"db\"]}', 'tags')").await,
+            Some("[\"db\"]".to_string())
+        );
+    }
+
+    #[tokio::test]
+    async fn missing_path_returns_null() {
+        assert_eq!(
+            single_text("SELECT lix_json_get('{\"name\":\"Ada\"}', 'missing')").await,
+            None
+        );
+    }
+}

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

@@ -0,0 +1,99 @@
+use std::any::Any;
+use std::sync::Arc;
+
+use datafusion::arrow::array::StringArray;
+use datafusion::arrow::datatypes::DataType;
+use datafusion::common::{plan_err, Result, ScalarValue};
+use datafusion::logical_expr::{
+    ColumnarValue, ScalarFunctionArgs, ScalarUDFImpl, Signature, Volatility,
+};
+use serde_json::Value as JsonValue;
+
+use super::common::{extract_json_path, json_text_value, scalar_inputs};
+
+#[derive(Debug, Clone, PartialEq, Eq, Hash)]
+pub(super) struct LixJsonGetText {
+    signature: Signature,
+}
+
+impl LixJsonGetText {
+    pub(super) fn new() -> Self {
+        Self {
+            signature: Signature::variadic_any(Volatility::Immutable),
+        }
+    }
+}
+
+impl ScalarUDFImpl for LixJsonGetText {
+    fn as_any(&self) -> &dyn Any {
+        self
+    }
+
+    fn name(&self) -> &str {
+        "lix_json_get_text"
+    }
+
+    fn signature(&self) -> &Signature {
+        &self.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.len() < 2 {
+            return plan_err!("lix_json_get_text requires at least 2 arguments");
+        }
+
+        let scalar_inputs = scalar_inputs(&args.args);
+        let arrays = ColumnarValue::values_to_arrays(&args.args)?;
+        let len = arrays.first().map(|array| array.len()).unwrap_or(1);
+
+        let mut values = Vec::with_capacity(len);
+        for row in 0..len {
+            values.push(match extract_json_path(self.name(), &arrays, row)? {
+                None | Some(JsonValue::Null) => None,
+                Some(JsonValue::Bool(value)) => Some(if value {
+                    "true".to_string()
+                } else {
+                    "false".to_string()
+                }),
+                Some(JsonValue::String(value)) => Some(value),
+                Some(other) => Some(json_text_value(&other)?),
+            });
+        }
+        if scalar_inputs {
+            Ok(ColumnarValue::Scalar(ScalarValue::Utf8(
+                values.into_iter().next().flatten(),
+            )))
+        } else {
+            Ok(ColumnarValue::Array(Arc::new(StringArray::from(values))))
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::super::test_support::single_text;
+
+    #[tokio::test]
+    async fn returns_unwrapped_text() {
+        assert_eq!(
+            single_text("SELECT lix_json_get_text('{\"name\":\"Ada\"}', 'name')").await,
+            Some("Ada".to_string())
+        );
+        assert_eq!(
+            single_text("SELECT lix_json_get_text('{\"active\":true}', 'active')").await,
+            Some("true".to_string())
+        );
+    }
+
+    #[tokio::test]
+    async fn missing_path_returns_null() {
+        assert_eq!(
+            single_text("SELECT lix_json_get_text('{\"name\":\"Ada\"}', 'missing')").await,
+            None
+        );
+    }
+}

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

@@ -0,0 +1,82 @@
+use std::any::Any;
+use std::sync::Arc;
+
+use datafusion::arrow::array::StringArray;
+use datafusion::arrow::datatypes::DataType;
+use datafusion::common::{plan_err, Result, ScalarValue};
+use datafusion::logical_expr::{
+    ColumnarValue, ScalarFunctionArgs, ScalarUDFImpl, Signature, Volatility,
+};
+
+use super::common::{decode_utf8_value, scalar_inputs, validate_utf8_encoding_arg};
+
+#[derive(Debug, Clone, PartialEq, Eq, Hash)]
+pub(super) struct LixTextDecode {
+    signature: Signature,
+}
+
+impl LixTextDecode {
+    pub(super) fn new() -> Self {
+        Self {
+            signature: Signature::one_of(
+                vec![Signature::any(1, Volatility::Immutable).type_signature],
+                Volatility::Immutable,
+            ),
+        }
+    }
+}
+
+impl ScalarUDFImpl for LixTextDecode {
+    fn as_any(&self) -> &dyn Any {
+        self
+    }
+
+    fn name(&self) -> &str {
+        "lix_text_decode"
+    }
+
+    fn signature(&self) -> &Signature {
+        &self.signature
+    }
+
+    fn return_type(&self, _arg_types: &[DataType]) -> Result<DataType> {
+        Ok(DataType::Utf8)
+    }
+
+    fn invoke_with_args(&self, args: ScalarFunctionArgs) -> Result<ColumnarValue> {
+        if !(1..=2).contains(&args.args.len()) {
+            return plan_err!("lix_text_decode requires 1 or 2 arguments");
+        }
+        validate_utf8_encoding_arg(self.name(), args.args.get(1))?;
+
+        let scalar_inputs = scalar_inputs(&args.args);
+        let arrays = ColumnarValue::values_to_arrays(&args.args)?;
+        let input = &arrays[0];
+        let len = input.len();
+
+        let mut values = Vec::with_capacity(len);
+        for row in 0..len {
+            values.push(decode_utf8_value(input.as_ref(), row)?);
+        }
+        if scalar_inputs {
+            Ok(ColumnarValue::Scalar(ScalarValue::Utf8(
+                values.into_iter().next().flatten(),
+            )))
+        } else {
+            Ok(ColumnarValue::Array(Arc::new(StringArray::from(values))))
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::super::test_support::single_text;
+
+    #[tokio::test]
+    async fn decodes_utf8_binary_to_text() {
+        assert_eq!(
+            single_text("SELECT lix_text_decode(X'416461')").await,
+            Some("Ada".to_string())
+        );
+    }
+}

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

@@ -0,0 +1,85 @@
+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,
+};
+
+use super::common::{
+    array_ref, binary_array_from_owned, encode_utf8_value, scalar_inputs,
+    validate_utf8_encoding_arg,
+};
+
+#[derive(Debug, Clone, PartialEq, Eq, Hash)]
+pub(super) struct LixTextEncode {
+    signature: Signature,
+}
+
+impl LixTextEncode {
+    pub(super) fn new() -> Self {
+        Self {
+            signature: Signature::one_of(
+                vec![Signature::any(1, Volatility::Immutable).type_signature],
+                Volatility::Immutable,
+            ),
+        }
+    }
+}
+
+impl ScalarUDFImpl for LixTextEncode {
+    fn as_any(&self) -> &dyn Any {
+        self
+    }
+
+    fn name(&self) -> &str {
+        "lix_text_encode"
+    }
+
+    fn signature(&self) -> &Signature {
+        &self.signature
+    }
+
+    fn return_type(&self, _arg_types: &[DataType]) -> Result<DataType> {
+        Ok(DataType::Binary)
+    }
+
+    fn invoke_with_args(&self, args: ScalarFunctionArgs) -> Result<ColumnarValue> {
+        if !(1..=2).contains(&args.args.len()) {
+            return plan_err!("lix_text_encode requires 1 or 2 arguments");
+        }
+        validate_utf8_encoding_arg(self.name(), args.args.get(1))?;
+
+        let scalar_inputs = scalar_inputs(&args.args);
+        let arrays = ColumnarValue::values_to_arrays(&args.args)?;
+        let input = &arrays[0];
+        let len = input.len();
+
+        let mut values = Vec::with_capacity(len);
+        for row in 0..len {
+            values.push(encode_utf8_value(input.as_ref(), row)?);
+        }
+        if scalar_inputs {
+            Ok(ColumnarValue::Scalar(ScalarValue::Binary(
+                values.into_iter().next().flatten(),
+            )))
+        } else {
+            Ok(ColumnarValue::Array(array_ref(binary_array_from_owned(
+                &values,
+            ))))
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::super::test_support::single_binary;
+
+    #[tokio::test]
+    async fn encodes_utf8_text_to_binary() {
+        assert_eq!(
+            single_binary("SELECT lix_text_encode('Ada')").await,
+            Some(b"Ada".to_vec())
+        );
+    }
+}

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

@@ -0,0 +1,76 @@
+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,
+};
+
+use crate::functions::FunctionProviderHandle;
+
+#[derive(Clone)]
+pub(super) struct LixUuidV7 {
+    pub(super) functions: FunctionProviderHandle,
+}
+
+impl PartialEq for LixUuidV7 {
+    fn eq(&self, _other: &Self) -> bool {
+        true
+    }
+}
+
+impl Eq for LixUuidV7 {}
+
+impl std::hash::Hash for LixUuidV7 {
+    fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
+        self.name().hash(state);
+    }
+}
+
+impl std::fmt::Debug for LixUuidV7 {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("LixUuidV7").finish()
+    }
+}
+
+impl ScalarUDFImpl for LixUuidV7 {
+    fn as_any(&self) -> &dyn Any {
+        self
+    }
+
+    fn name(&self) -> &str {
+        "lix_uuid_v7"
+    }
+
+    fn signature(&self) -> &Signature {
+        static SIGNATURE: std::sync::LazyLock<Signature> =
+            std::sync::LazyLock::new(|| Signature::nullary(Volatility::Volatile));
+        &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_uuid_v7 requires no arguments");
+        }
+        Ok(ColumnarValue::Scalar(ScalarValue::Utf8(Some(
+            self.functions.call_uuid_v7(),
+        ))))
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::super::test_support::single_text;
+
+    #[tokio::test]
+    async fn returns_uuid_text() {
+        let value = single_text("SELECT lix_uuid_v7()")
+            .await
+            .expect("uuid should not be null");
+        assert!(!value.is_empty());
+    }
+}

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

@@ -0,0 +1,82 @@
+mod common;
+mod lix_active_version_commit_id;
+mod lix_empty_blob;
+mod lix_json;
+mod lix_json_get;
+mod lix_json_get_text;
+mod lix_text_decode;
+mod lix_text_encode;
+mod lix_uuid_v7;
+
+use datafusion::execution::context::SessionContext;
+use datafusion::logical_expr::ScalarUDF;
+
+use crate::functions::FunctionProviderHandle;
+
+#[cfg(test)]
+pub(crate) fn system_sql2_function_provider() -> FunctionProviderHandle {
+    use crate::functions::{FunctionProvider, SharedFunctionProvider, SystemFunctionProvider};
+
+    SharedFunctionProvider::new(Box::new(SystemFunctionProvider) as Box<dyn FunctionProvider + Send>)
+}
+
+pub(crate) fn register_sql2_functions(
+    ctx: &SessionContext,
+    functions: FunctionProviderHandle,
+    active_version_commit_id: Option<String>,
+) {
+    ctx.register_udf(ScalarUDF::from(
+        lix_active_version_commit_id::LixActiveVersionCommitId::new(active_version_commit_id),
+    ));
+    ctx.register_udf(ScalarUDF::from(lix_json_get::LixJsonGet::new()));
+    ctx.register_udf(ScalarUDF::from(lix_json_get_text::LixJsonGetText::new()));
+    ctx.register_udf(ScalarUDF::from(lix_text_decode::LixTextDecode::new()));
+    ctx.register_udf(ScalarUDF::from(lix_text_encode::LixTextEncode::new()));
+    ctx.register_udf(ScalarUDF::from(lix_json::LixJson));
+    ctx.register_udf(ScalarUDF::from(lix_empty_blob::LixEmptyBlob));
+    ctx.register_udf(ScalarUDF::from(lix_uuid_v7::LixUuidV7 { functions }));
+}
+
+#[cfg(test)]
+pub(super) mod test_support {
+    use datafusion::arrow::array::{Array, BinaryArray, StringArray};
+    use datafusion::prelude::SessionContext;
+
+    use super::{register_sql2_functions, system_sql2_function_provider};
+
+    pub(super) async fn single_text(sql: &str) -> Option<String> {
+        let ctx = SessionContext::new();
+        register_sql2_functions(&ctx, system_sql2_function_provider(), None);
+        let batches = ctx
+            .sql(sql)
+            .await
+            .expect("query should plan")
+            .collect()
+            .await
+            .expect("query should execute");
+        let array = batches[0]
+            .column(0)
+            .as_any()
+            .downcast_ref::<StringArray>()
+            .expect("first column should be utf8");
+        (!array.is_null(0)).then(|| array.value(0).to_string())
+    }
+
+    pub(super) async fn single_binary(sql: &str) -> Option<Vec<u8>> {
+        let ctx = SessionContext::new();
+        register_sql2_functions(&ctx, system_sql2_function_provider(), None);
+        let batches = ctx
+            .sql(sql)
+            .await
+            .expect("query should plan")
+            .collect()
+            .await
+            .expect("query should execute");
+        let array = batches[0]
+            .column(0)
+            .as_any()
+            .downcast_ref::<BinaryArray>()
+            .expect("first column should be binary");
+        (!array.is_null(0)).then(|| array.value(0).to_vec())
+    }
+}