mapleFU commented on code in PR #177: URL: https://github.com/apache/iceberg-cpp/pull/177#discussion_r2290554993
########## src/iceberg/expression/term.h: ########## @@ -0,0 +1,267 @@ +/* + * 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. + */ + +#pragma once + +/// \file iceberg/expression/term.h +/// Term interface for Iceberg expressions - represents values that can be evaluated. + +#include <memory> +#include <string> +#include <string_view> + +#include "iceberg/arrow_c_data.h" +#include "iceberg/expression/literal.h" +#include "iceberg/type_fwd.h" +#include "iceberg/util/formattable.h" + +namespace iceberg { + +// TODO(gangwu): add a struct-like interface to wrap a row of data from ArrowArray or +// structs like ManifestFile and ManifestEntry to facilitate generailization of the +// evaluation of expressions on top of different data structures. +class StructLike; + +/// \brief A term is an expression node that produces a typed value when evaluated. +class ICEBERG_EXPORT Term : public util::Formattable { + public: + enum class Kind : uint8_t { kReference = 0, kTransform, kExtract }; + + /// \brief Returns the kind of this term. + virtual Kind kind() const = 0; +}; + +/// \brief Interface for unbound expressions that need schema binding. +/// +/// Unbound expressions contain string-based references that must be resolved +/// against a concrete schema to produce bound expressions that can be evaluated. +/// +/// \tparam B The bound type this term produces when binding is successful +template <typename B> +class ICEBERG_EXPORT Unbound { + public: + /// \brief Bind this expression to a concrete schema. + /// + /// \param schema The schema to bind against + /// \param case_sensitive Whether field name matching should be case sensitive + /// \return A bound expression or an error if binding fails + virtual Result<std::shared_ptr<B>> Bind(const Schema& schema, + bool case_sensitive) const = 0; + + /// \brief Overloaded Bind method that uses case-sensitive matching by default. + Result<std::shared_ptr<B>> Bind(const Schema& schema) const; + + /// \brief Returns the underlying named reference for this unbound term. + virtual std::shared_ptr<class NamedReference> reference() = 0; +}; + +/// \brief Interface for bound expressions that can be evaluated. +/// +/// Bound expressions have been resolved against a concrete schema and contain +/// all necessary information to evaluate against data structures. +class ICEBERG_EXPORT Bound { + public: + virtual ~Bound(); + + /// \brief Evaluate this expression against a row-based data. + virtual Result<Literal::Value> Evaluate(const StructLike& data) const = 0; + + /// \brief Evaluate this expression against an Arrow array. + virtual Result<std::vector<Literal::Value>> Evaluate(const ArrowArray& data) const = 0; + + /// \brief Returns the underlying bound reference for this term. + virtual std::shared_ptr<class BoundReference> reference() = 0; +}; + +/// \brief Base class for unbound terms. +/// +/// \tparam B The bound type this term produces when binding is successful. +template <typename B> +class ICEBERG_EXPORT UnboundTerm : public Unbound<B>, public Term { + public: + using BoundType = B; +}; + +/// \brief Base class for bound terms. +class ICEBERG_EXPORT BoundTerm : public Bound, public Term { + public: + ~BoundTerm() override; + + /// \brief Returns the type produced by this term. + virtual std::shared_ptr<Type> type() const = 0; Review Comment: would `const std::shared_ptr<Type>&` a better choice? ########## src/iceberg/expression/predicate.h: ########## @@ -0,0 +1,210 @@ +/* + * 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. + */ + +#pragma once + +/// \file iceberg/expression/predicate.h +/// Predicate interface for boolean expressions that test terms. + +#include "iceberg/expression/expression.h" +#include "iceberg/expression/term.h" + +namespace iceberg { + +/// \brief A predicate is a boolean expression that tests a term against some criteria. +/// +/// \tparam TermType The type of the term being tested +template <typename TermType> Review Comment: I'm thinking a bit that whether these can be concepts, but this is not a blocking issue ########## src/iceberg/expression/predicate.h: ########## @@ -0,0 +1,210 @@ +/* + * 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. + */ + +#pragma once + +/// \file iceberg/expression/predicate.h +/// Predicate interface for boolean expressions that test terms. + +#include "iceberg/expression/expression.h" +#include "iceberg/expression/term.h" + +namespace iceberg { + +/// \brief A predicate is a boolean expression that tests a term against some criteria. +/// +/// \tparam TermType The type of the term being tested +template <typename TermType> +class ICEBERG_EXPORT Predicate : public Expression { + public: + /// \brief Create a predicate with an operation and term. + /// + /// \param op The operation this predicate performs + /// \param term The term this predicate tests + Predicate(Expression::Operation op, std::shared_ptr<TermType> term); + + ~Predicate() override; + + Expression::Operation op() const override { return operation_; } + + /// \brief Returns the term this predicate tests. + const std::shared_ptr<TermType>& term() const { return term_; } + + protected: + Expression::Operation operation_; + std::shared_ptr<TermType> term_; +}; + +/// \brief Unbound predicates contain unbound terms and must be bound to a concrete schema +/// before they can be evaluated. +/// +/// \tparam B The bound type this predicate produces when binding is successful +template <typename B> +class ICEBERG_EXPORT UnboundPredicate : public Predicate<UnboundTerm<B>>, + public Unbound<Expression> { + using BASE = Predicate<UnboundTerm<B>>; + + public: + UnboundPredicate(Expression::Operation op, std::shared_ptr<UnboundTerm<B>> term); + UnboundPredicate(Expression::Operation op, std::shared_ptr<UnboundTerm<B>> term, + Literal value); + UnboundPredicate(Expression::Operation op, std::shared_ptr<UnboundTerm<B>> term, + std::vector<Literal> values); + + ~UnboundPredicate() override; + + std::shared_ptr<NamedReference> reference() override { + return BASE::term()->reference(); + } + + std::string ToString() const override; + + /// \brief Bind this UnboundPredicate. + Result<std::shared_ptr<Expression>> Bind(const Schema& schema, + bool case_sensitive) const override; + + Result<std::shared_ptr<Expression>> Negate() const override; + + private: + Result<std::shared_ptr<Expression>> BindUnaryOperation( + std::shared_ptr<B> bound_term) const; + Result<std::shared_ptr<Expression>> BindLiteralOperation( + std::shared_ptr<B> bound_term) const; + Result<std::shared_ptr<Expression>> BindInOperation( + std::shared_ptr<B> bound_term) const; + + private: + std::vector<Literal> values_; +}; + +/// \brief Bound predicates contain bound terms and can be evaluated. +class ICEBERG_EXPORT BoundPredicate : public Predicate<BoundTerm>, public Bound { + public: + BoundPredicate(Expression::Operation op, std::shared_ptr<BoundTerm> term); + + ~BoundPredicate() override; + + using Predicate<BoundTerm>::op; + + using Predicate<BoundTerm>::term; + + std::shared_ptr<BoundReference> reference() override { return term_->reference(); } + + Result<Literal::Value> Evaluate(const StructLike& data) const override; + + Result<std::vector<Literal::Value>> Evaluate(const ArrowArray& data) const override; + + /// \brief Test a value against this predicate. + /// + /// \param value The value to test + /// \return true if the predicate passes, false otherwise + virtual Result<bool> Test(const Literal::Value& value) const = 0; + + enum class Kind : int8_t { + // A unary predicate (tests for null, not-null, etc.). + kUnary = 0, + // A literal predicate (compares against a literal). + kLiteral, + // A set predicate (tests membership in a set). + kIn, Review Comment: kSet? ########## src/iceberg/expression/term.h: ########## @@ -0,0 +1,258 @@ +/* + * 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. + */ + +#pragma once + +/// \file iceberg/expression/term.h +/// Term interface for Iceberg expressions - represents values that can be evaluated. + +#include <memory> +#include <string> +#include <string_view> + +#include "iceberg/arrow_c_data.h" +#include "iceberg/expression/literal.h" +#include "iceberg/iceberg_export.h" +#include "iceberg/result.h" +#include "iceberg/type_fwd.h" + +namespace iceberg { + +// TODO(gangwu): add a struct-like interface to wrap a row of data from ArrowArray or +// structs like ManifestFile and ManifestEntry to facilitate generailization of the +// evaluation of expressions on top of different data structures. +class StructLike; + +/// \brief A term is an expression node that produces a typed value when evaluated. +class ICEBERG_EXPORT Term { + public: + virtual ~Term() = default; + + /// \brief Returns a string representation of this term. + virtual std::string ToString() const = 0; +}; + +/// \brief Interface for unbound expressions that need schema binding. +/// +/// Unbound expressions contain string-based references that must be resolved +/// against a concrete schema to produce bound expressions that can be evaluated. +/// +/// \tparam B The bound type this term produces when binding is successful +template <typename B> +class ICEBERG_EXPORT Unbound { + public: + virtual ~Unbound() = default; + + /// \brief Bind this expression to a concrete schema. + /// + /// \param schema The schema to bind against + /// \param case_sensitive Whether field name matching should be case sensitive + /// \return A bound expression or an error if binding fails + virtual Result<std::unique_ptr<B>> Bind(const Schema& schema, + bool case_sensitive) const = 0; + + /// \brief Overloaded Bind method that uses case-sensitive matching by default. + Result<std::unique_ptr<B>> Bind(const Schema& schema) const; + + /// \brief Returns the underlying named reference for this unbound term. + virtual std::shared_ptr<class NamedReference> reference() = 0; +}; + +/// \brief Interface for bound expressions that can be evaluated. +/// +/// Bound expressions have been resolved against a concrete schema and contain +/// all necessary information to evaluate against data structures. +class ICEBERG_EXPORT Bound { + public: + virtual ~Bound() = default; + + /// \brief Evaluate this expression against a row-based data. + virtual Result<Literal::Value> Evaluate(const StructLike& data) const = 0; + + /// \brief Evaluate this expression against an Arrow array. + virtual Result<std::vector<Literal::Value>> Evaluate(const ArrowArray& data) const = 0; + + /// \brief Returns the underlying bound reference for this term. + virtual std::shared_ptr<class BoundReference> reference() = 0; +}; + +/// \brief Base class for unbound terms. +/// +/// \tparam B The bound type this term produces when binding is successful. +template <typename B> +class ICEBERG_EXPORT UnboundTerm : public Unbound<B>, public Term { + public: + using BoundType = B; + + ~UnboundTerm() override = default; +}; + +/// \brief Base class for bound terms. +class ICEBERG_EXPORT BoundTerm : public Bound, public Term { + public: + ~BoundTerm() override = default; + + /// \brief Returns the type produced by this term. + virtual const std::shared_ptr<Type>& type() const = 0; + + /// \brief Returns whether this term may produce null values. + virtual bool MayProduceNull() const = 0; + + // TODO(gangwu): add a comparator function to Literal and BoundTerm. + + /// \brief Returns whether this term is equivalent to another. + /// + /// Two terms are equivalent if they produce the same values when evaluated. + /// + /// \param other Another bound term to compare against + /// \return true if the terms are equivalent, false otherwise + virtual bool Equals(const BoundTerm& other) const = 0; +}; + +/// \brief A reference represents a named field in an expression. +class ICEBERG_EXPORT Reference { + public: + virtual ~Reference() = default; + + /// \brief Returns the name of the referenced field. + virtual std::string_view name() const = 0; +}; + +/// \brief A reference to an unbound named field. +class ICEBERG_EXPORT NamedReference + : public Reference, + public UnboundTerm<BoundReference>, + public std::enable_shared_from_this<NamedReference> { + public: + /// \brief Create a named reference to a field. + /// + /// \param field_name The name of the field to reference + explicit NamedReference(std::string field_name); + + ~NamedReference() override = default; + + std::string_view name() const override { return field_name_; } + + Result<std::unique_ptr<BoundReference>> Bind(const Schema& schema, + bool case_sensitive) const override; + + std::shared_ptr<NamedReference> reference() override { return shared_from_this(); } + + std::string ToString() const override; + + private: + std::string field_name_; +}; + +/// \brief A reference to a bound field. +class ICEBERG_EXPORT BoundReference + : public Reference, + public BoundTerm, + public std::enable_shared_from_this<BoundReference> { + public: + /// \brief Create a bound reference. + /// + /// \param field The schema field + explicit BoundReference(std::shared_ptr<SchemaField> field); + + ~BoundReference() override = default; + + const SchemaField& field() const { return *field_; } + + std::string_view name() const override { return field_->name(); } + + std::string ToString() const override; + + Result<Literal::Value> Evaluate(const StructLike& data) const override; + + Result<std::vector<Literal::Value>> Evaluate(const ArrowArray& data) const override; Review Comment: Ok, this is ok to me ########## src/iceberg/expression/expressions.h: ########## @@ -0,0 +1,263 @@ +/* + * 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. + */ + +#pragma once + +/// \file iceberg/expression/expressions.h +/// Factory methods for creating expressions. + +#include <initializer_list> +#include <memory> +#include <string> +#include <vector> + +#include "iceberg/expression/literal.h" +#include "iceberg/expression/predicate.h" +#include "iceberg/expression/term.h" +#include "iceberg/iceberg_export.h" + +namespace iceberg { + +/// \brief Factory methods for creating expressions. +class ICEBERG_EXPORT Expressions { + public: + // Logical operations + + /// \brief Create an AND expression. + static std::shared_ptr<Expression> And(std::shared_ptr<Expression> left, + std::shared_ptr<Expression> right); + + /// \brief Create an OR expression. + static std::shared_ptr<Expression> Or(std::shared_ptr<Expression> left, + std::shared_ptr<Expression> right); + + // Transform functions + + /// \brief Create a bucket transform term. + static std::shared_ptr<UnboundTransform> Bucket(std::string name, int32_t num_buckets); + + /// \brief Create a year transform term. + static std::shared_ptr<UnboundTransform> Year(std::string name); + + /// \brief Create a month transform term. + static std::shared_ptr<UnboundTransform> Month(std::string name); + + /// \brief Create a day transform term. + static std::shared_ptr<UnboundTransform> Day(std::string name); + + /// \brief Create an hour transform term. + static std::shared_ptr<UnboundTransform> Hour(std::string name); + + /// \brief Create a truncate transform term. + static std::shared_ptr<UnboundTransform> Truncate(std::string name, int32_t width); + + /// \brief Create a transform expression. + static std::shared_ptr<UnboundTransform> Transform( + std::string name, std::shared_ptr<Transform> transform); + + // Unary predicates + + /// \brief Create an IS NULL predicate for a field name. + static std::shared_ptr<UnboundPredicate<BoundReference>> IsNull(std::string name); + + /// \brief Create an IS NULL predicate for an unbound term. + template <typename B> + static std::shared_ptr<UnboundPredicate<B>> IsNull( + std::shared_ptr<UnboundTerm<B>> expr); + + /// \brief Create a NOT NULL predicate for a field name. + static std::shared_ptr<UnboundPredicate<BoundReference>> NotNull(std::string name); + + /// \brief Create a NOT NULL predicate for an unbound term. + template <typename B> + static std::shared_ptr<UnboundPredicate<B>> NotNull( + std::shared_ptr<UnboundTerm<B>> expr); + + /// \brief Create an IS NaN predicate for a field name. + static std::shared_ptr<UnboundPredicate<BoundReference>> IsNaN(std::string name); + + /// \brief Create an IS NaN predicate for an unbound term. + template <typename B> + static std::shared_ptr<UnboundPredicate<B>> IsNaN(std::shared_ptr<UnboundTerm<B>> expr); + + /// \brief Create a NOT NaN predicate for a field name. + static std::shared_ptr<UnboundPredicate<BoundReference>> NotNaN(std::string name); + + /// \brief Create a NOT NaN predicate for an unbound term. + template <typename B> + static std::shared_ptr<UnboundPredicate<B>> NotNaN( + std::shared_ptr<UnboundTerm<B>> expr); + + // Comparison predicates + + /// \brief Create a less than predicate for a field name. + static std::shared_ptr<UnboundPredicate<BoundReference>> LessThan(std::string name, + Literal value); + + /// \brief Create a less than predicate for an unbound term. + template <typename B> + static std::shared_ptr<UnboundPredicate<B>> LessThan( + std::shared_ptr<UnboundTerm<B>> expr, Literal value); + + /// \brief Create a less than or equal predicate for a field name. + static std::shared_ptr<UnboundPredicate<BoundReference>> LessThanOrEqual( + std::string name, Literal value); + + /// \brief Create a less than or equal predicate for an unbound term. + template <typename B> + static std::shared_ptr<UnboundPredicate<B>> LessThanOrEqual( + std::shared_ptr<UnboundTerm<B>> expr, Literal value); + + /// \brief Create a greater than predicate for a field name. + static std::shared_ptr<UnboundPredicate<BoundReference>> GreaterThan(std::string name, + Literal value); + + /// \brief Create a greater than predicate for an unbound term. + template <typename B> + static std::shared_ptr<UnboundPredicate<B>> GreaterThan( + std::shared_ptr<UnboundTerm<B>> expr, Literal value); + + /// \brief Create a greater than or equal predicate for a field name. + static std::shared_ptr<UnboundPredicate<BoundReference>> GreaterThanOrEqual( + std::string name, Literal value); + + /// \brief Create a greater than or equal predicate for an unbound term. + template <typename B> + static std::shared_ptr<UnboundPredicate<B>> GreaterThanOrEqual( + std::shared_ptr<UnboundTerm<B>> expr, Literal value); + + /// \brief Create an equal predicate for a field name. + static std::shared_ptr<UnboundPredicate<BoundReference>> Equal(std::string name, + Literal value); + + /// \brief Create an equal predicate for an unbound term. + template <typename B> + static std::shared_ptr<UnboundPredicate<B>> Equal(std::shared_ptr<UnboundTerm<B>> expr, + Literal value); + + /// \brief Create a not equal predicate for a field name. + static std::shared_ptr<UnboundPredicate<BoundReference>> NotEqual(std::string name, + Literal value); + + /// \brief Create a not equal predicate for an unbound term. + template <typename B> + static std::shared_ptr<UnboundPredicate<B>> NotEqual( + std::shared_ptr<UnboundTerm<B>> expr, Literal value); + + // String predicates + + /// \brief Create a starts with predicate for a field name. + static std::shared_ptr<UnboundPredicate<BoundReference>> StartsWith(std::string name, + std::string value); + + /// \brief Create a starts with predicate for an unbound term. + template <typename B> + static std::shared_ptr<UnboundPredicate<B>> StartsWith( + std::shared_ptr<UnboundTerm<B>> expr, std::string value); + + /// \brief Create a not starts with predicate for a field name. + static std::shared_ptr<UnboundPredicate<BoundReference>> NotStartsWith( + std::string name, std::string value); + + /// \brief Create a not starts with predicate for an unbound term. + template <typename B> + static std::shared_ptr<UnboundPredicate<B>> NotStartsWith( + std::shared_ptr<UnboundTerm<B>> expr, std::string value); + + // Set predicates + + /// \brief Create an IN predicate for a field name. + static std::shared_ptr<UnboundPredicate<BoundReference>> In( + std::string name, std::vector<Literal> values); + + /// \brief Create an IN predicate for an unbound term. + template <typename B> + static std::shared_ptr<UnboundPredicate<B>> In(std::shared_ptr<UnboundTerm<B>> expr, + std::vector<Literal> values); + + /// \brief Create an IN predicate for a field name with initializer list. + static std::shared_ptr<UnboundPredicate<BoundReference>> In( + std::string name, std::initializer_list<Literal> values); Review Comment: curiously why somewhere initializer list, other places vector? -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
