statelydb 0.30.0 → 0.31.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e351019a0ad023595d08e9bf19a94facc2d1b92d00682516b929a2fe7c5593f7
-  data.tar.gz: d347e52bee873414dfa4709d9be9a3a6fae27cbb0482a369bc725224c863eea5
+  metadata.gz: 27ff426cc92aa94367beb63a0c568cec999cdf69c1e77385742e589b933f1162
+  data.tar.gz: 9244139c26ba6f3000f70966e11fba71b3188300b30632f84c31df2a5760effb
 SHA512:
-  metadata.gz: faf9e62e260a7c05b57071ae982105d03de3edc23137d5c068e9478afa5a5c03ed2367caca7f698a41c8b9e71862b49006ce6898db1a828bb5ec393df6d8eccf
-  data.tar.gz: e731ba43fdb7699136c2ffdd82f2ff6e2a1b83fe317371ccfb994f657b3a3260d04d5246e1e518470a48e8f9b1295c4118b220a3a2bdb90b24b578cdde82b708
+  metadata.gz: a806985ceb7c1a5a186343a155f2e8536823a371b8c3aea4bd682f3fe7b2a0ca4197a16117bb0d0ca42656946b7c6b3de77f243adcc02bfd8a2edc6e620eb8dc
+  data.tar.gz: 6f35612802f0189f14356515132277cfa7d3825fed0a5b6ff70c5dfa9071040a4e01d025d944fb5618c6171c604774e68821c24e3f76fb86ea5edab33248d16c

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
@@ -129,8 +131,23 @@ module StatelyDB
     # @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
@@ -149,6 +166,7 @@ module StatelyDB
                    sort_property: nil,
                    sort_direction: :ascending,
                    item_types: [],
+                   cel_filters: [],
                    gt: nil,
                    gte: nil,
                    lt: nil,
@@ -163,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,
@@ -211,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.
@@ -223,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?
@@ -230,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
       )

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
@@ -335,8 +337,23 @@ module StatelyDB
       # @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
@@ -358,6 +375,7 @@ module StatelyDB
                      sort_property: nil,
                      sort_direction: :ascending,
                      item_types: [],
+                     cel_filters: [],
                      gt: nil,
                      gte: nil,
                      lt: nil,
@@ -386,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.30.0"
+  VERSION = "0.31.0"
 end

data/rbi/statelydb.rbi

@@ -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.
@@ -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

@@ -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)
@@ -900,6 +904,7 @@ module StatelyDB
                         ?sort_property: untyped,
                         ?sort_direction: untyped,
                         ?item_types: untyped,
+                        ?cel_filters: untyped,
                         ?gt: untyped,
                         ?gte: untyped,
                         ?lt: untyped,

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: statelydb
 version: !ruby/object:Gem::Version
-  version: 0.30.0
+  version: 0.31.0
 platform: ruby
 authors:
 - Stately Cloud, Inc.
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-06-26 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