[VARIANT] Add support for the json_to_variant API

parquet-variant/Cargo.toml

@@ -35,7 +35,10 @@ rust-version = "1.83"
 [dependencies]
 arrow-schema = { workspace = true }
 chrono = { workspace = true }
-serde_json = "1.0"
+# "arbitrary_precision" allows us to manually parse numbers. "preserve_order" does not automatically
+# sort object keys
+serde_json = { version = "1.0" }
+rust_decimal = "1.37.2"
 base64 = "0.22"
 indexmap = "2.10.0"
 

parquet-variant/examples/variant_from_json_examples.rs

@@ -0,0 +1,50 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Example showing how to convert Variant values to JSON
+
+use parquet_variant::{
+    json_to_variant, variant_to_json, variant_to_json_string, variant_to_json_value, VariantBuilder,
+};
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let person_string = "{\"name\":\"Alice\", \"age\":30, ".to_string()
+        + "\"email\":\"[email protected]\", \"is_active\": true, \"score\": 95.7,"
+        + "\"additional_info\": null}";
+
+    let mut variant_builder = VariantBuilder::new();
+    json_to_variant(&person_string, &mut variant_builder)?;
+
+    let (metadata, value) = variant_builder.finish();
+
+    let variant = parquet_variant::Variant::try_new(&metadata, &value)?;
+
+    let json_result = variant_to_json_string(&variant)?;
+    let json_value = variant_to_json_value(&variant)?;
+    let pretty_json = serde_json::to_string_pretty(&json_value)?;
+    println!("{pretty_json}");
+
+    let mut buffer = Vec::new();
+    variant_to_json(&mut buffer, &variant)?;
+    let buffer_result = String::from_utf8(buffer)?;
+    assert_eq!(json_result, "{\"additional_info\":null,\"age\":30,".to_string() +
+    "\"email\":\"[email protected]\",\"is_active\":true,\"name\":\"Alice\",\"score\":95.7}");
+    assert_eq!(json_result, buffer_result);
+    assert_eq!(json_result, serde_json::to_string(&json_value)?);
+
+    Ok(())
+}

parquet-variant/src/builder.rs

@@ -756,6 +756,44 @@ impl<'a, 'b> ObjectBuilder<'a, 'b> {
     }
 }
 
+/// Trait that abstracts functionality from Variant fconstruction implementations, namely
+/// `VariantBuilder`, `ListBuilder` and `ObjectFieldBuilder` to minimize code duplication.
+pub(crate) trait VariantBuilderExt {
+    fn append_value<'m, 'd, T: Into<Variant<'m, 'd>>>(&mut self, value: T);
+
+    fn new_list(&mut self) -> ListBuilder;
+
+    fn new_object(&mut self) -> ObjectBuilder;
+}
+
+impl VariantBuilderExt for ListBuilder<'_> {
+    fn append_value<'m, 'd, T: Into<Variant<'m, 'd>>>(&mut self, value: T) {
+        self.append_value(value);
+    }
+
+    fn new_list(&mut self) -> ListBuilder {
+        self.new_list()
+    }
+
+    fn new_object(&mut self) -> ObjectBuilder {
+        self.new_object()
+    }
+}
+
+impl VariantBuilderExt for VariantBuilder {
+    fn append_value<'m, 'd, T: Into<Variant<'m, 'd>>>(&mut self, value: T) {
+        self.append_value(value);
+    }
+
+    fn new_list(&mut self) -> ListBuilder {
+        self.new_list()
+    }
+
+    fn new_object(&mut self) -> ObjectBuilder {
+        self.new_object()
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;

parquet-variant/src/from_json.rs

@@ -0,0 +1,149 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Module for parsing JSON strings as Variant
+
+use crate::{ListBuilder, ObjectBuilder, Variant, VariantBuilder, VariantBuilderExt};
+use arrow_schema::ArrowError;
+use serde_json::{Number, Value};
+
+/// Converts a JSON string to Variant using [`VariantBuilder`]. The resulting `value` and `metadata`
+/// buffers can be extracted using `builder.finish()`
+///
+/// # Arguments
+/// * `json` - The JSON string to parse as Variant.
+/// * `variant_builder` - Object of type `VariantBuilder` used to build the vatiant from the JSON
+///   string
+///
+/// # Returns
+///
+/// * `Ok(())` if successful
+/// * `Err` with error details if the conversion fails
+///
+/// ```rust
+/// # use parquet_variant::{
+/// json_to_variant, variant_to_json, variant_to_json_string, variant_to_json_value, VariantBuilder
+/// };
+///
+/// let mut variant_builder = VariantBuilder::new();
+/// let person_string = "{\"name\":\"Alice\", \"age\":30, ".to_string()
+/// + "\"email\":\"[email protected]\", \"is_active\": true, \"score\": 95.7,"
+/// + "\"additional_info\": null}";
+/// json_to_variant(&person_string, &mut variant_builder)?;
+///
+/// let (metadata, value) = variant_builder.finish();
+///
+/// let variant = parquet_variant::Variant::try_new(&metadata, &value)?;
+///
+/// let json_result = variant_to_json_string(&variant)?;
+/// let json_value = variant_to_json_value(&variant)?;
+///
+/// let mut buffer = Vec::new();
+/// variant_to_json(&mut buffer, &variant)?;
+/// let buffer_result = String::from_utf8(buffer)?;
+/// assert_eq!(json_result, "{\"additional_info\":null,\"age\":30,".to_string() +
+/// "\"email\":\"[email protected]\",\"is_active\":true,\"name\":\"Alice\",\"score\":95.7}");
+/// assert_eq!(json_result, buffer_result);
+/// assert_eq!(json_result, serde_json::to_string(&json_value)?);
+/// # Ok::<(), Box<dyn std::error::Error>>(())
+/// ```
+pub fn json_to_variant(json: &str, builder: &mut VariantBuilder) -> Result<(), ArrowError> {
+    let json: Value = serde_json::from_str(json)
+        .map_err(|e| ArrowError::InvalidArgumentError(format!("JSON format error: {e}")))?;
+
+    build_json(&json, builder)?;
+    Ok(())
+}
+
+fn build_json(json: &Value, builder: &mut VariantBuilder) -> Result<(), ArrowError> {
+    append_json(json, builder)?;
+    Ok(())
+}
+
+fn variant_from_number<'a, 'b>(n: &Number) -> Result<Variant<'a, 'b>, ArrowError> {
+    if let Some(i) = n.as_i64() {
+        // Find minimum Integer width to fit
+        if i as i8 as i64 == i {
+            Ok((i as i8).into())
+        } else if i as i16 as i64 == i {
+            Ok((i as i16).into())
+        } else if i as i32 as i64 == i {
+            Ok((i as i32).into())
+        } else {
+            Ok(i.into())
+        }
+    } else {
+        // Todo: Try decimal once we implement custom JSON parsing where we have access to strings
+        // Try double - currently json_to_variant does not produce decimal
+        match n.as_f64() {
+            Some(f) => return Ok(f.into()),
+            None => Err(ArrowError::InvalidArgumentError(format!(
+                "Failed to parse {} as number",
+                n.to_string()
+            ))),
+        }?
+    }
+}
+
+fn append_json(json: &Value, builder: &mut impl VariantBuilderExt) -> Result<(), ArrowError> {
+    match json {
+        Value::Null => builder.append_value(Variant::Null),
+        Value::Bool(b) => builder.append_value(*b),
+        Value::Number(n) => {
+            builder.append_value(variant_from_number(n)?);
+        }
+        Value::String(s) => builder.append_value(s.as_str()),
+        Value::Array(arr) => {
+            let mut list_builder = builder.new_list();
+            for val in arr {
+                append_json(val, &mut list_builder)?;
+            }
+            list_builder.finish();
+        }
+        Value::Object(obj) => {
+            let mut obj_builder = builder.new_object();
+            for (key, value) in obj.iter() {
+                let mut field_builder = ObjectFieldBuilder {
+                    key,
+                    builder: &mut obj_builder,
+                };
+                append_json(value, &mut field_builder)?;
+            }
+            obj_builder.finish().unwrap();
+        }
+    };
+    Ok(())
+}
+
+struct ObjectFieldBuilder<'a, 'b, 'c> {
+    key: &'a str,
+    builder: &'b mut ObjectBuilder<'c, 'a>,
+}
+
+impl VariantBuilderExt for ObjectFieldBuilder<'_, '_, '_> {
+    fn append_value<'m, 'd, T: Into<Variant<'m, 'd>>>(&mut self, value: T) {
+        self.builder.insert(self.key, value);
+    }
+
+    fn new_list(&mut self) -> ListBuilder {
+        self.builder.new_list(self.key)
+    }
+
+    fn new_object(&mut self) -> ObjectBuilder {
+        self.builder.new_object(self.key)
+    }
+}

parquet-variant/src/lib.rs

@@ -33,10 +33,12 @@ mod decoder;
 mod variant;
 // TODO: dead code removal
 mod builder;
+mod from_json;
 mod to_json;
 #[allow(dead_code)]
 mod utils;
 
 pub use builder::*;
+pub use from_json::json_to_variant;
 pub use to_json::{variant_to_json, variant_to_json_string, variant_to_json_value};
 pub use variant::*;

parquet-variant/src/variant/decimal.rs

@@ -86,8 +86,8 @@ pub struct VariantDecimal4 {
 }
 
 impl VariantDecimal4 {
-    const MAX_PRECISION: u8 = 9;
-    const MAX_UNSCALED_VALUE: u32 = u32::pow(10, Self::MAX_PRECISION as u32) - 1;
+    pub(crate) const MAX_PRECISION: u8 = 9;
+    pub(crate) const MAX_UNSCALED_VALUE: u32 = u32::pow(10, Self::MAX_PRECISION as u32) - 1;
 
     pub fn try_new(integer: i32, scale: u8) -> Result<Self, ArrowError> {
         decimal_try_new!(integer, scale)
@@ -136,8 +136,8 @@ pub struct VariantDecimal8 {
 }
 
 impl VariantDecimal8 {
-    const MAX_PRECISION: u8 = 18;
-    const MAX_UNSCALED_VALUE: u64 = u64::pow(10, Self::MAX_PRECISION as u32) - 1;
+    pub(crate) const MAX_PRECISION: u8 = 18;
+    pub(crate) const MAX_UNSCALED_VALUE: u64 = u64::pow(10, Self::MAX_PRECISION as u32) - 1;
 
     pub fn try_new(integer: i64, scale: u8) -> Result<Self, ArrowError> {
         decimal_try_new!(integer, scale)