arrow/extension/parquet_variant.h

0001 // Licensed to the Apache Software Foundation (ASF) under one
0002 // or more contributor license agreements.  See the NOTICE file
0003 // distributed with this work for additional information
0004 // regarding copyright ownership.  The ASF licenses this file
0005 // to you under the Apache License, Version 2.0 (the
0006 // "License"); you may not use this file except in compliance
0007 // with the License.  You may obtain a copy of the License at
0008 //
0009 //   http://www.apache.org/licenses/LICENSE-2.0
0010 //
0011 // Unless required by applicable law or agreed to in writing,
0012 // software distributed under the License is distributed on an
0013 // "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
0014 // KIND, either express or implied.  See the License for the
0015 // specific language governing permissions and limitations
0016 // under the License.
0017
0018 #pragma once
0019
0020 #include <string>
0021
0022 #include "arrow/extension_type.h"
0023 #include "arrow/util/visibility.h"
0024
0025 namespace arrow::extension {
0026
0027 class ARROW_EXPORT VariantArray : public ExtensionArray {
0028  public:
0029   using ExtensionArray::ExtensionArray;
0030 };
0031
0032 /// EXPERIMENTAL: Variant is not yet fully supported.
0033 ///
0034 /// Variant supports semi-structured objects that can be composed of
0035 /// primitives, arrays, and objects, which can be queried by path.
0036 ///
0037 /// Unshredded variant representation:
0038 /// optional group variant_name (VARIANT) {
0039 ///   required binary metadata;
0040 ///   required binary value;
0041 /// }
0042 ///
0043 /// To read more about variant encoding, see the variant encoding spec at
0044 /// https://github.com/apache/parquet-format/blob/master/VariantEncoding.md
0045 ///
0046 /// To read more about variant shredding, see the variant shredding spec at
0047 /// https://github.com/apache/parquet-format/blob/master/VariantShredding.md
0048 class ARROW_EXPORT VariantExtensionType : public ExtensionType {
0049  public:
0050   explicit VariantExtensionType(const std::shared_ptr<DataType>& storage_type);
0051
0052   std::string extension_name() const override { return "arrow.parquet.variant"; }
0053
0054   bool ExtensionEquals(const ExtensionType& other) const override;
0055
0056   Result<std::shared_ptr<DataType>> Deserialize(
0057       std::shared_ptr<DataType> storage_type,
0058       const std::string& serialized_data) const override;
0059
0060   std::string Serialize() const override;
0061
0062   std::shared_ptr<Array> MakeArray(std::shared_ptr<ArrayData> data) const override;
0063
0064   static Result<std::shared_ptr<DataType>> Make(std::shared_ptr<DataType> storage_type);
0065
0066   static bool IsSupportedStorageType(const std::shared_ptr<DataType>& storage_type);
0067
0068   std::shared_ptr<Field> metadata() const { return metadata_; }
0069
0070   std::shared_ptr<Field> value() const { return value_; }
0071
0072  private:
0073   // TODO GH-45948 added shredded_value
0074   std::shared_ptr<Field> metadata_;
0075   std::shared_ptr<Field> value_;
0076 };
0077
0078 /// \brief Return a VariantExtensionType instance.
0079 ARROW_EXPORT std::shared_ptr<DataType> variant(std::shared_ptr<DataType> storage_type);
0080
0081 }  // namespace arrow::extension