statelydb 0.29.0 → 0.31.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6d5953d075d48d8ca4449644bb88fe0792587f00da52e29d0937b02416b0c0a0
-  data.tar.gz: 424e94dd43130382ec000b986d701581dd3a76a7e404ae7c4d2f0b3f3d8927b1
+  metadata.gz: 27ff426cc92aa94367beb63a0c568cec999cdf69c1e77385742e589b933f1162
+  data.tar.gz: 9244139c26ba6f3000f70966e11fba71b3188300b30632f84c31df2a5760effb
 SHA512:
-  metadata.gz: 2f4c26cdb3399124ee45110ad92611551a64d14df7548d92a537797eef804191d538c267bfc82d9c6c20f9e2f3812fd13f9f4fcfb3b60339df743b265b05e1e9
-  data.tar.gz: 4661408175189b2ef7320a145bee131404eb0b6a542b00e846dfb8fee0a4d3fdbdfb660d43a675b7362d5b7b94d6e17c3fd0a63cda284e624e4d13419ab7b3be
+  metadata.gz: a806985ceb7c1a5a186343a155f2e8536823a371b8c3aea4bd682f3fe7b2a0ca4197a16117bb0d0ca42656946b7c6b3de77f243adcc02bfd8a2edc6e620eb8dc
+  data.tar.gz: 6f35612802f0189f14356515132277cfa7d3825fed0a5b6ff70c5dfa9071040a4e01d025d944fb5618c6171c604774e68821c24e3f76fb86ea5edab33248d16c

data/lib/api/db/list_filters_pb.rb

@@ -5,7 +5,7 @@
 require 'google/protobuf'
 
 
-descriptor_data = "\n\x15\x64\x62/list_filters.proto\x12\nstately.db\"9\n\x0f\x46ilterCondition\x12\x1d\n\titem_type\x18\x01 \x01(\tH\x00R\x08itemTypeB\x07\n\x05valueBk\n\x0e\x63om.stately.dbB\x10ListFiltersProtoP\x01\xa2\x02\x03SDX\xaa\x02\nStately.Db\xca\x02\nStately\\Db\xe2\x02\x16Stately\\Db\\GPBMetadata\xea\x02\x0bStately::Dbb\x06proto3"
+descriptor_data = "\n\x15\x64\x62/list_filters.proto\x12\nstately.db\"}\n\x0f\x46ilterCondition\x12\x1d\n\titem_type\x18\x01 \x01(\tH\x00R\x08itemType\x12\x42\n\x0e\x63\x65l_expression\x18\x02 \x01(\x0b\x32\x19.stately.db.CelExpressionH\x00R\rcelExpressionB\x07\n\x05value\"L\n\rCelExpression\x12\x1b\n\titem_type\x18\x01 \x01(\tR\x08itemType\x12\x1e\n\nexpression\x18\x02 \x01(\tR\nexpressionBk\n\x0e\x63om.stately.dbB\x10ListFiltersProtoP\x01\xa2\x02\x03SDX\xaa\x02\nStately.Db\xca\x02\nStately\\Db\xe2\x02\x16Stately\\Db\\GPBMetadata\xea\x02\x0bStately::Dbb\x06proto3"
 
 pool = ::Google::Protobuf::DescriptorPool.generated_pool
 pool.add_serialized_file(descriptor_data)
@@ -13,5 +13,6 @@ pool.add_serialized_file(descriptor_data)
 module Stately
   module Db
     FilterCondition = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("stately.db.FilterCondition").msgclass
+    CelExpression = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("stately.db.CelExpression").msgclass
   end
 end

data/lib/common/build_filters.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "api/db/service_services_pb"
+
+def build_filters(item_types: [], cel_filters: [])
+  filters = item_types.map do |item_type|
+    Stately::Db::FilterCondition.new(item_type: item_type.respond_to?(:name) ? item_type.name.split("::").last : item_type)
+  end
+  filters += cel_filters.map do |filter|
+    Stately::Db::FilterCondition.new(
+      cel_expression: {
+        item_type: filter[0].respond_to?(:name) ? filter[0].name.split("::").last : filter[0],
+        expression: filter[1]
+      }
+    )
+  end
+  filters
+end

data/lib/statelydb.rb

@@ -4,6 +4,7 @@ require "api/db/service_services_pb"
 require "common/auth/auth_token_provider"
 require "common/auth/interceptor"
 require "common/net/conn"
+require "common/build_filters"
 require "common/error_interceptor"
 require "grpc"
 require "json"
@@ -16,6 +17,7 @@ require "key_path"
 require "token"
 require "uuid"
 
+# StatelyDB -- the home of all StatelyDB Ruby SDK classes and modules.
 module StatelyDB
   # CoreClient is a low level client for interacting with the Stately Cloud API.
   # This client shouldn't be used directly in most cases. Instead, use the generated
@@ -84,7 +86,7 @@ module StatelyDB
 
     # Fetch a single Item from a StatelyDB Store at the given key_path.
     #
-    # @param key_path [String] the path to the item
+    # @param key_path [StatelyDB::KeyPath, String] the path to the item
     # @return [StatelyDB::Item, NilClass] the Item or nil if not found
     # @raise [StatelyDB::Error] if the parameters are invalid or if the item is not found
     #
@@ -99,7 +101,8 @@ module StatelyDB
 
     # Fetch a batch of up to 100 Items from a StatelyDB Store at the given key_paths.
     #
-    # @param key_paths [String, Array<String>] the paths to the items. Max 100 key paths.
+    # @param key_paths [StatelyDB::KeyPath, String, Array<StatelyDB::KeyPath, String>] the paths
+    #   to the items. Max 100 key paths.
     # @return [Array<StatelyDB::Item>, NilClass] the items or nil if not found
     # @raise [StatelyDB::Error] if the parameters are invalid or if the item is not found
     #
@@ -124,12 +127,27 @@ module StatelyDB
 
     # Begin listing Items from a StatelyDB Store at the given prefix.
     #
-    # @param prefix [String] the prefix to list
+    # @param prefix [StatelyDB::KeyPath, String] the prefix to list
     # @param limit [Integer] the maximum number of items to return
     # @param sort_property [String] the property to sort by
     # @param sort_direction [Symbol, String, Integer] the direction to sort by (:ascending or :descending)
-    # @param item_types [Array<Class, String>] the item types to filter by. The returned
+    # @param item_types [Array<Class<StatelyDB::Item>, String>] the item types to filter by. The returned
     #   items will be instances of one of these types.
+    # @param cel_filters [Array<Array<Class, String>, String>>] An optional list of
+    #   item_type, cel_expression tuples that represent CEL expressions to filter the
+    #   results set by. Use the cel_filter helper function to build these expressions.
+    #   CEL expressions are only evaluated for the item type they are defined for, and
+    #   do not affect other item types in the result set. This means if an item type has
+    #   no CEL filter and there are no item_type filters constraints, it will be included
+    #   in the result set.
+    #   In the context of a CEL expression, the key-word `this` refers to the item being
+    #   evaluated, and property properties should be accessed by the names as they appear
+    #   in schema -- not necessarily as they appear in the generated code for a particular
+    #   language. For example, if you have a `Movie` item type with the property `rating`,
+    #   you could write a CEL expression like `this.rating == 'R'` to return only movies
+    #   that are rated `R`.
+    #   Find the full CEL language definition here:
+    #   https://github.com/google/cel-spec/blob/master/doc/langdef.md
     # @param gt [StatelyDB::KeyPath | String] filters results to only include items with a key greater than the
     #   specified value based on lexicographic ordering.
     # @param gte [StatelyDB::KeyPath | String] filters results to only include items with a key greater than or equal to the
@@ -148,6 +166,7 @@ module StatelyDB
                    sort_property: nil,
                    sort_direction: :ascending,
                    item_types: [],
+                   cel_filters: [],
                    gt: nil,
                    gte: nil,
                    lt: nil,
@@ -162,15 +181,14 @@ module StatelyDB
       key_conditions = key_condition_params
                        .reject { |(_, value)| value.nil? }
                        .map { |(operator, key_path)| Stately::Db::KeyCondition.new(operator: operator, key_path: key_path) }
+
       req = Stately::Db::BeginListRequest.new(
         store_id: @store_id,
         key_path_prefix: String(prefix),
         limit:,
         sort_property:,
         sort_direction:,
-        filter_conditions: item_types.map do |item_type|
-          Stately::Db::FilterCondition.new(item_type: item_type.respond_to?(:name) ? item_type.name.split("::").last : item_type)
-        end,
+        filter_conditions: build_filters(item_types: item_types, cel_filters: cel_filters),
         key_conditions: key_conditions,
         allow_stale: @allow_stale,
         schema_id: @schema::SCHEMA_ID,
@@ -210,8 +228,23 @@ module StatelyDB
     #   then the first page of results will be returned which may empty because it
     #   does not contain items of your selected item types. Be sure to check
     #   token.can_continue to see if there are more results to fetch.
-    # @param item_types [Array<Class, String>] the item types to filter by. The returned
+    # @param item_types [Array<StatelyDB::Item, String>] the item types to filter by. The returned
     #   items will be instances of one of these types.
+    # @param cel_filters [Array<Array<Class, String>, String>>] An optional list of
+    #   item_type, cel_expression tuples that represent CEL expressions to filter the
+    #   results set by. Use the cel_filter helper function to build these expressions.
+    #   CEL expressions are only evaluated for the item type they are defined for, and
+    #   do not affect other item types in the result set. This means if an item type has
+    #   no CEL filter and there are no item_type filters constraints, it will be included
+    #   in the result set.
+    #   In the context of a CEL expression, the key-word `this` refers to the item being
+    #   evaluated, and property properties should be accessed by the names as they appear
+    #   in schema -- not necessarily as they appear in the generated code for a particular
+    #   language. For example, if you have a `Movie` item type with the property `rating`,
+    #   you could write a CEL expression like `this.rating == 'R'` to return only movies
+    #   that are rated `R`.
+    #   Find the full CEL language definition here:
+    #   https://github.com/google/cel-spec/blob/master/doc/langdef.md
     # @param total_segments [Integer] the total number of segments to divide the
     #   scan into. Use this when you want to parallelize your operation.
     # @param segment_index [Integer] the index of the segment to scan.
@@ -222,6 +255,7 @@ module StatelyDB
     #   client.data.begin_scan(limit: 10, item_types: [MyItem])
     def begin_scan(limit: 0,
                    item_types: [],
+                   cel_filters: [],
                    total_segments: nil,
                    segment_index: nil)
       if total_segments.nil? != segment_index.nil?
@@ -229,12 +263,11 @@ module StatelyDB
                                    code: GRPC::Core::StatusCodes::INVALID_ARGUMENT,
                                    stately_code: "InvalidArgument")
       end
+
       req = Stately::Db::BeginScanRequest.new(
         store_id: @store_id,
         limit:,
-        filter_condition: item_types.map do |item_type|
-          Stately::Db::FilterCondition.new(item_type: item_type.respond_to?(:name) ? item_type.name.split("::").last : item_type)
-        end,
+        filter_condition: build_filters(item_types: item_types, cel_filters: cel_filters),
         schema_id: @schema::SCHEMA_ID,
         schema_version_id: @schema::SCHEMA_VERSION_ID
       )
@@ -350,7 +383,8 @@ module StatelyDB
 
     # Delete up to 50 Items from a StatelyDB Store at the given key_paths.
     #
-    # @param key_paths [String, Array<String>] the paths to the items. Max 50 key paths.
+    # @param key_paths [StatelyDB::KeyPath, String, Array<StatelyDB::KeyPath, String>] the paths
+    #   to the items. Max 50 key paths.
     # @raise [StatelyDB::Error] if the parameters are invalid
     # @raise [StatelyDB::Error] if the item is not found
     # @return [void] nil

data/lib/transaction/transaction.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "common/build_filters"
+
 module StatelyDB
   module Transaction
     # Transaction coordinates sending requests and waiting for responses. Consumers should not need
@@ -178,7 +180,7 @@ module StatelyDB
       # Fetch Items from a StatelyDB Store at the given key_path. Note that Items need to exist before being retrieved inside a
       # transaction.
       #
-      # @param key_path [String] the path to the item
+      # @param key_path [StatelyDB::KeyPath, String] the path to the item
       # @return [StatelyDB::Item, NilClass] the item or nil if not found
       # @raise [StatelyDB::Error::InvalidParameters] if the parameters are invalid
       # @raise [StatelyDB::Error::NotFound] if the item is not found
@@ -198,7 +200,7 @@ module StatelyDB
       # key_paths. Note that Items need to exist before being retrieved inside a
       # transaction.
       #
-      # @param key_paths [String, Array<String>] the paths to the items. Max 100
+      # @param key_paths [StatelyDB::KeyPath, String, Array<StatelyDB::KeyPath, String>] the paths to the items. Max 100
       # key paths.
       # @return [Array<StatelyDB::Item>] the items
       # @raise [StatelyDB::Error::InvalidParameters] if the parameters are invalid
@@ -310,7 +312,8 @@ module StatelyDB
       # Delete up to 50 Items from a StatelyDB Store at the given key_paths. Results are not returned until the transaction is
       # committed and will be available in the Result object returned by commit.
       #
-      # @param key_paths [String, Array<String>] the paths to the items. Max 50 key paths.
+      # @param key_paths [StatelyDB::KeyPath, String, Array<StatelyDB::KeyPath, String>] the paths
+      #   to the items. Max 50 key paths.
       # @return [void] nil
       #
       # Example:
@@ -330,12 +333,27 @@ module StatelyDB
 
       # Begin listing Items from a StatelyDB Store at the given prefix.
       #
-      # @param prefix [String] the prefix to list
+      # @param prefix [StatelyDB::KeyPath, String] the prefix to list
       # @param limit [Integer] the maximum number of items to return
       # @param sort_property [String] the property to sort by
       # @param sort_direction [Symbol] the direction to sort by (:ascending or :descending)
-      # @param item_types [Array<Class, String>] the item types to filter by. The returned
+      # @param item_types [Array<StatelyDB::Item, String>] the item types to filter by. The returned
       #   items will be instances of one of these types.
+      # @param cel_filters [Array<Array<Class, String>, String>>] An optional list of
+      #   item_type, cel_expression tuples that represent CEL expressions to filter the
+      #   results set by. Use the cel_filter helper function to build these expressions.
+      #   CEL expressions are only evaluated for the item type they are defined for, and
+      #   do not affect other item types in the result set. This means if an item type has
+      #   no CEL filter and there are no item_type filters constraints, it will be included
+      #   in the result set.
+      #   In the context of a CEL expression, the key-word `this` refers to the item being
+      #   evaluated, and property properties should be accessed by the names as they appear
+      #   in schema -- not necessarily as they appear in the generated code for a particular
+      #   language. For example, if you have a `Movie` item type with the property `rating`,
+      #   you could write a CEL expression like `this.rating == 'R'` to return only movies
+      #   that are rated `R`.
+      #   Find the full CEL language definition here:
+      #   https://github.com/google/cel-spec/blob/master/doc/langdef.md
       # @param gt [StatelyDB::KeyPath | String] filters results to only include items with a key greater than the
       #   specified value based on lexicographic ordering.
       # @param gte [StatelyDB::KeyPath | String] filters results to only include items with a key greater than or equal to the
@@ -357,6 +375,7 @@ module StatelyDB
                      sort_property: nil,
                      sort_direction: :ascending,
                      item_types: [],
+                     cel_filters: [],
                      gt: nil,
                      gte: nil,
                      lt: nil,
@@ -385,11 +404,7 @@ module StatelyDB
             limit:,
             sort_property:,
             sort_direction:,
-            filter_conditions: item_types.map do |item_type|
-              Stately::Db::FilterCondition.new(
-                item_type: item_type.respond_to?(:name) ? item_type.name.split("::").last : item_type
-              )
-            end,
+            filter_conditions: build_filters(item_types: item_types, cel_filters: cel_filters),
             key_conditions: key_conditions
           )
         )

data/lib/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module StatelyDB
-  VERSION = "0.29.0"
+  VERSION = "0.31.0"
 end

data/rbi/db/list_filters_pb.rbi

@@ -8,29 +8,55 @@ class Stately::Db::FilterCondition
 
   sig do
     params(
-      item_type: T.nilable(String)
+      item_type: T.nilable(String),
+      cel_expression: T.nilable(Stately::Db::CelExpression)
     ).void
   end
   def initialize(
-    item_type: ""
+    item_type: "",
+    cel_expression: nil
   )
   end
 
-  # item_type is the type of item to filter by.
+  # item_type is the type of item to include in a query response.
   sig { returns(String) }
   def item_type
   end
 
-  # item_type is the type of item to filter by.
+  # item_type is the type of item to include in a query response.
   sig { params(value: String).void }
   def item_type=(value)
   end
 
-  # item_type is the type of item to filter by.
+  # item_type is the type of item to include in a query response.
   sig { void }
   def clear_item_type
   end
 
+  # cel_expression is a CEL expression to evaluate against a specific item type.
+# If an expression evaluates to true, the item is included in the results.
+# This expression *only* applies to the item type specified in the
+# CelExpression.item_type field, and is not applied to other item types in the query.
+  sig { returns(T.nilable(Stately::Db::CelExpression)) }
+  def cel_expression
+  end
+
+  # cel_expression is a CEL expression to evaluate against a specific item type.
+# If an expression evaluates to true, the item is included in the results.
+# This expression *only* applies to the item type specified in the
+# CelExpression.item_type field, and is not applied to other item types in the query.
+  sig { params(value: T.nilable(Stately::Db::CelExpression)).void }
+  def cel_expression=(value)
+  end
+
+  # cel_expression is a CEL expression to evaluate against a specific item type.
+# If an expression evaluates to true, the item is included in the results.
+# This expression *only* applies to the item type specified in the
+# CelExpression.item_type field, and is not applied to other item types in the query.
+  sig { void }
+  def clear_cel_expression
+  end
+
   sig { returns(T.nilable(Symbol)) }
   def value
   end
@@ -67,3 +93,100 @@ class Stately::Db::FilterCondition
   def self.descriptor
   end
 end
+
+class Stately::Db::CelExpression
+  include ::Google::Protobuf::MessageExts
+  extend ::Google::Protobuf::MessageExts::ClassMethods
+
+  sig do
+    params(
+      item_type: T.nilable(String),
+      expression: T.nilable(String)
+    ).void
+  end
+  def initialize(
+    item_type: "",
+    expression: ""
+  )
+  end
+
+  # item_type is the itemType to evaluate the expression against.
+  sig { returns(String) }
+  def item_type
+  end
+
+  # item_type is the itemType to evaluate the expression against.
+  sig { params(value: String).void }
+  def item_type=(value)
+  end
+
+  # item_type is the itemType to evaluate the expression against.
+  sig { void }
+  def clear_item_type
+  end
+
+  # expression is the CEL expression to evaluate.
+# If the expression evaluates to true, the item is included in the results,
+# otherwise it is excluded.
+#
+# In the context of the CEL expression, 'this' refers to the item being evaluated.
+# For example, the expression is "this.foo == 'bar'" means that the item
+# must have a property 'foo' with the value 'bar' to be included in the results.
+  sig { returns(String) }
+  def expression
+  end
+
+  # expression is the CEL expression to evaluate.
+# If the expression evaluates to true, the item is included in the results,
+# otherwise it is excluded.
+#
+# In the context of the CEL expression, 'this' refers to the item being evaluated.
+# For example, the expression is "this.foo == 'bar'" means that the item
+# must have a property 'foo' with the value 'bar' to be included in the results.
+  sig { params(value: String).void }
+  def expression=(value)
+  end
+
+  # expression is the CEL expression to evaluate.
+# If the expression evaluates to true, the item is included in the results,
+# otherwise it is excluded.
+#
+# In the context of the CEL expression, 'this' refers to the item being evaluated.
+# For example, the expression is "this.foo == 'bar'" means that the item
+# must have a property 'foo' with the value 'bar' to be included in the results.
+  sig { void }
+  def clear_expression
+  end
+
+  sig { params(field: String).returns(T.untyped) }
+  def [](field)
+  end
+
+  sig { params(field: String, value: T.untyped).void }
+  def []=(field, value)
+  end
+
+  sig { returns(T::Hash[Symbol, T.untyped]) }
+  def to_h
+  end
+
+  sig { params(str: String).returns(Stately::Db::CelExpression) }
+  def self.decode(str)
+  end
+
+  sig { params(msg: Stately::Db::CelExpression).returns(String) }
+  def self.encode(msg)
+  end
+
+  sig { params(str: String, kw: T.untyped).returns(Stately::Db::CelExpression) }
+  def self.decode_json(str, **kw)
+  end
+
+  sig { params(msg: Stately::Db::CelExpression, kw: T.untyped).returns(String) }
+  def self.encode_json(msg, **kw)
+  end
+
+  sig { returns(::Google::Protobuf::Descriptor) }
+  def self.descriptor
+  end
+end

data/rbi/statelydb.rbi

@@ -245,7 +245,7 @@ module StatelyDB
     # ```ruby
     # client.get("/ItemType-identifier")
     # ```
-    sig { params(key_path: String).returns(T.any(StatelyDB::Item, NilClass)) }
+    sig { params(key_path: T.any(StatelyDB::KeyPath, String)).returns(T.any(StatelyDB::Item, NilClass)) }
     def get(key_path); end
 
     # Fetch a batch of up to 100 Items from a StatelyDB Store at the given key_paths.
@@ -257,7 +257,7 @@ module StatelyDB
     # ```ruby
     # client.data.get_batch("/ItemType-identifier", "/ItemType-identifier2")
     # ```
-    sig { params(key_paths: T.any(String, T::Array[String])).returns(T.any(T::Array[StatelyDB::Item], NilClass)) }
+    sig { params(key_paths: T.any(StatelyDB::KeyPath, String, T::Array[T.any(StatelyDB::KeyPath, String)])).returns(T.any(T::Array[StatelyDB::Item], NilClass)) }
     def get_batch(*key_paths); end
 
     # _@return_ — the list of Items and the token
@@ -272,13 +272,14 @@ module StatelyDB
         sort_property: T.untyped,
         sort_direction: T.untyped,
         item_types: T.untyped,
+        cel_filters: T.untyped,
         gt: T.untyped,
         gte: T.untyped,
         lt: T.untyped,
         lte: T.untyped
       ).returns(T.any(T::Array[StatelyDB::Item], StatelyDB::Token))
     end
-    def begin_list(prefix, limit: 100, sort_property: nil, sort_direction: :ascending, item_types: [], gt: nil, gte: nil, lt: nil, lte: nil); end
+    def begin_list(prefix, limit: 100, sort_property: nil, sort_direction: :ascending, item_types: [], cel_filters: [], gt: nil, gte: nil, lt: nil, lte: nil); end
 
     # Continue listing Items from a StatelyDB Store using a token.
     # 
@@ -305,6 +306,8 @@ module StatelyDB
     # 
     # _@param_ `item_types` — the item types to filter by. The returned items will be instances of one of these types.
     # 
+    # _@param_ `cel_filters` — ] An optional list of item_type, cel_expression tuples that represent CEL expressions to filter the results set by. Use the cel_filter helper function to build these expressions. CEL expressions are only evaluated for the item type they are defined for, and do not affect other item types in the result set. This means if an item type has no CEL filter and there are no item_type filters constraints, it will be included in the result set. In the context of a CEL expression, the key-word `this` refers to the item being evaluated, and property properties should be accessed by the names as they appear in schema -- not necessarily as they appear in the generated code for a particular language. For example, if you have a `Movie` item type with the property `rating`, you could write a CEL expression like `this.rating == 'R'` to return only movies that are rated `R`. Find the full CEL language definition here: https://github.com/google/cel-spec/blob/master/doc/langdef.md
+    # 
     # _@param_ `total_segments` — the total number of segments to divide the scan into. Use this when you want to parallelize your operation.
     # 
     # _@param_ `segment_index` — the index of the segment to scan. Use this when you want to parallelize your operation.
@@ -317,12 +320,13 @@ module StatelyDB
     sig do
       params(
         limit: Integer,
-        item_types: T::Array[T.any(T::Class[T.anything], String)],
+        item_types: T::Array[T.any(StatelyDB::Item, String)],
+        cel_filters: T::Array[T.any(T::Array[T.any(T::Class[T.anything], String)], String)],
         total_segments: T.nilable(Integer),
         segment_index: T.nilable(Integer)
       ).returns(T.any(T::Array[StatelyDB::Item], StatelyDB::Token))
     end
-    def begin_scan(limit: 0, item_types: [], total_segments: nil, segment_index: nil); end
+    def begin_scan(limit: 0, item_types: [], cel_filters: [], total_segments: nil, segment_index: nil); end
 
     # continue_scan takes the token from a begin_scan call and returns more results
     # based on the original request parameters and pagination options.
@@ -400,7 +404,7 @@ module StatelyDB
     # ```ruby
     # client.data.delete("/ItemType-identifier", "/ItemType-identifier2")
     # ```
-    sig { params(key_paths: T.any(String, T::Array[String])).void }
+    sig { params(key_paths: T.any(StatelyDB::KeyPath, String, T::Array[T.any(StatelyDB::KeyPath, String)])).void }
     def delete(*key_paths); end
 
     # Transaction takes a block and executes the block within a transaction.
@@ -927,7 +931,7 @@ module StatelyDB
       #   item = txn.get("/ItemType-identifier")
       # end
       # ```
-      sig { params(key_path: String).returns(T.any(StatelyDB::Item, NilClass)) }
+      sig { params(key_path: T.any(StatelyDB::KeyPath, String)).returns(T.any(StatelyDB::Item, NilClass)) }
       def get(key_path); end
 
       # Fetch a batch of up to 100 Items from a StatelyDB Store at the given
@@ -943,7 +947,7 @@ module StatelyDB
       # _@param_ `key_paths` — the paths to the items. Max 100
       # 
       # _@return_ — the items
-      sig { params(key_paths: T.any(String, T::Array[String])).returns(T::Array[StatelyDB::Item]) }
+      sig { params(key_paths: T.any(StatelyDB::KeyPath, String, T::Array[T.any(StatelyDB::KeyPath, String)])).returns(T::Array[StatelyDB::Item]) }
       def get_batch(*key_paths); end
 
       # Put a single Item into a StatelyDB store. Results are not returned until the transaction is
@@ -1003,7 +1007,7 @@ module StatelyDB
       # _@param_ `key_paths` — the paths to the items. Max 50 key paths.
       # 
       # _@return_ — nil
-      sig { params(key_paths: T.any(String, T::Array[String])).void }
+      sig { params(key_paths: T.any(StatelyDB::KeyPath, String, T::Array[T.any(StatelyDB::KeyPath, String)])).void }
       def delete(*key_paths); end
 
       # Example:
@@ -1020,13 +1024,14 @@ module StatelyDB
           sort_property: T.untyped,
           sort_direction: T.untyped,
           item_types: T.untyped,
+          cel_filters: T.untyped,
           gt: T.untyped,
           gte: T.untyped,
           lt: T.untyped,
           lte: T.untyped
         ).returns([T::Array[StatelyDB::Item], ::Stately::Db::ListToken])
       end
-      def begin_list(prefix, limit: 100, sort_property: nil, sort_direction: :ascending, item_types: [], gt: nil, gte: nil, lt: nil, lte: nil); end
+      def begin_list(prefix, limit: 100, sort_property: nil, sort_direction: :ascending, item_types: [], cel_filters: [], gt: nil, gte: nil, lt: nil, lte: nil); end
 
       # Continue listing Items from a StatelyDB Store using a token.
       # 

data/sig/statelydb.rbs

@@ -208,7 +208,7 @@ module StatelyDB
     # ```ruby
     # client.get("/ItemType-identifier")
     # ```
-    def get: (String key_path) -> (StatelyDB::Item | NilClass)
+    def get: ((StatelyDB::KeyPath | String) key_path) -> (StatelyDB::Item | NilClass)
 
     # Fetch a batch of up to 100 Items from a StatelyDB Store at the given key_paths.
     # 
@@ -219,7 +219,7 @@ module StatelyDB
     # ```ruby
     # client.data.get_batch("/ItemType-identifier", "/ItemType-identifier2")
     # ```
-    def get_batch: (*(String | ::Array[String]) key_paths) -> (::Array[StatelyDB::Item] | NilClass)
+    def get_batch: (*(StatelyDB::KeyPath | String | ::Array[(StatelyDB::KeyPath | String)]) key_paths) -> (::Array[StatelyDB::Item] | NilClass)
 
     # _@return_ — the list of Items and the token
     # 
@@ -232,6 +232,7 @@ module StatelyDB
                       ?sort_property: untyped,
                       ?sort_direction: untyped,
                       ?item_types: untyped,
+                      ?cel_filters: untyped,
                       ?gt: untyped,
                       ?gte: untyped,
                       ?lt: untyped,
@@ -262,6 +263,8 @@ module StatelyDB
     # 
     # _@param_ `item_types` — the item types to filter by. The returned items will be instances of one of these types.
     # 
+    # _@param_ `cel_filters` — ] An optional list of item_type, cel_expression tuples that represent CEL expressions to filter the results set by. Use the cel_filter helper function to build these expressions. CEL expressions are only evaluated for the item type they are defined for, and do not affect other item types in the result set. This means if an item type has no CEL filter and there are no item_type filters constraints, it will be included in the result set. In the context of a CEL expression, the key-word `this` refers to the item being evaluated, and property properties should be accessed by the names as they appear in schema -- not necessarily as they appear in the generated code for a particular language. For example, if you have a `Movie` item type with the property `rating`, you could write a CEL expression like `this.rating == 'R'` to return only movies that are rated `R`. Find the full CEL language definition here: https://github.com/google/cel-spec/blob/master/doc/langdef.md
+    # 
     # _@param_ `total_segments` — the total number of segments to divide the scan into. Use this when you want to parallelize your operation.
     # 
     # _@param_ `segment_index` — the index of the segment to scan. Use this when you want to parallelize your operation.
@@ -273,7 +276,8 @@ module StatelyDB
     # ```
     def begin_scan: (
                       ?limit: Integer,
-                      ?item_types: ::Array[(Class | String)],
+                      ?item_types: ::Array[(StatelyDB::Item | String)],
+                      ?cel_filters: ::Array[(::Array[(Class | String)] | String)],
                       ?total_segments: Integer?,
                       ?segment_index: Integer?
                     ) -> (::Array[StatelyDB::Item] | StatelyDB::Token)
@@ -350,7 +354,7 @@ module StatelyDB
     # ```ruby
     # client.data.delete("/ItemType-identifier", "/ItemType-identifier2")
     # ```
-    def delete: (*(String | ::Array[String]) key_paths) -> void
+    def delete: (*(StatelyDB::KeyPath | String | ::Array[(StatelyDB::KeyPath | String)]) key_paths) -> void
 
     # Transaction takes a block and executes the block within a transaction.
     # If the block raises an exception, the transaction is rolled back.
@@ -813,7 +817,7 @@ module StatelyDB
       #   item = txn.get("/ItemType-identifier")
       # end
       # ```
-      def get: (String key_path) -> (StatelyDB::Item | NilClass)
+      def get: ((StatelyDB::KeyPath | String) key_path) -> (StatelyDB::Item | NilClass)
 
       # Fetch a batch of up to 100 Items from a StatelyDB Store at the given
       # key_paths. Note that Items need to exist before being retrieved inside a
@@ -828,7 +832,7 @@ module StatelyDB
       # _@param_ `key_paths` — the paths to the items. Max 100
       # 
       # _@return_ — the items
-      def get_batch: (*(String | ::Array[String]) key_paths) -> ::Array[StatelyDB::Item]
+      def get_batch: (*(StatelyDB::KeyPath | String | ::Array[(StatelyDB::KeyPath | String)]) key_paths) -> ::Array[StatelyDB::Item]
 
       # Put a single Item into a StatelyDB store. Results are not returned until the transaction is
       # committed and will be available in the Result object returned by commit. An identifier for
@@ -885,7 +889,7 @@ module StatelyDB
       # _@param_ `key_paths` — the paths to the items. Max 50 key paths.
       # 
       # _@return_ — nil
-      def delete: (*(String | ::Array[String]) key_paths) -> void
+      def delete: (*(StatelyDB::KeyPath | String | ::Array[(StatelyDB::KeyPath | String)]) key_paths) -> void
 
       # Example:
       #   client.data.transaction do |txn|
@@ -900,6 +904,7 @@ module StatelyDB
                         ?sort_property: untyped,
                         ?sort_direction: untyped,
                         ?item_types: untyped,
+                        ?cel_filters: untyped,
                         ?gt: untyped,
                         ?gte: untyped,
                         ?lt: untyped,
@@ -1008,6 +1013,7 @@ module Stately
     TransactionListResponse: untyped
     TransactionFinished: untyped
     FilterCondition: untyped
+    CelExpression: untyped
     ContinueListRequest: untyped
     ContinueListDirection: untyped
     ContinueScanRequest: untyped

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: statelydb
 version: !ruby/object:Gem::Version
-  version: 0.29.0
+  version: 0.31.0
 platform: ruby
 authors:
 - Stately Cloud, Inc.
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-06-25 00:00:00.000000000 Z
+date: 2025-06-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async
@@ -99,6 +99,7 @@ files:
 - lib/common/auth/interceptor.rb
 - lib/common/auth/token_fetcher.rb
 - lib/common/auth/token_provider.rb
+- lib/common/build_filters.rb
 - lib/common/error_interceptor.rb
 - lib/common/net/conn.rb
 - lib/error.rb