purplelight 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fa2f2cd3bfef440892736ed8fdf65431b38e89fec7fe5c71e5fcb3f99c3ce053
-  data.tar.gz: dae1eed495f1c832a88a9c45b45b144a8ae39601ea0ca5ce390d1a834fdffffd
+  metadata.gz: '07534009e367f28d3374708991cb870f5fa168ee11a95142af8d357885af7abc'
+  data.tar.gz: e665d587dea94999326c0c42e88d2bcfd99bae01e305aee9e3051d3ddcd266e2
 SHA512:
-  metadata.gz: bbb4db5c11a6c12c71f721874b9d9c3724a9280e5b03105954108f39353fd1000d651c6ac4eb7261c003751d03c62a7950488df33881ac1ebdc46e4c9a986e11
-  data.tar.gz: 86bcd3d0ebd0221d71c8fd55c07a79dc9a0a635335f70d1cb1a96b56deef3d477876d4953f88e3700275832bfeb48628754ce7ff4591036efcd2bc383acadc98
+  metadata.gz: e4cabf4d438a8afa0d00902aa07b01320013f4e8588630fb2d5c4f9b2432e1910ac94c19ccce78bdb396a415ac3ea949527b83d22eadfbc036520656c4273869
+  data.tar.gz: b038e1fa40f36e985571019d7b4d7fe9c5013ea17314640f8d484ca9cbbb68292af08c5f91b1a006f34c473a24f3b83b03aece33d333685afb749437ac920ca4

data/README.md

@@ -9,7 +9,7 @@ Purplelight is published on RubyGems: [purplelight on RubyGems](https://rubygems
 Add to your Gemfile:
 
 ```ruby
-gem 'purplelight', '~> 0.1.1'
+gem 'purplelight', '~> 0.1.2'
 ```
 
 Or install directly:
@@ -41,6 +41,60 @@ Purplelight.snapshot(
 )
 ```
 
+### Filtering with `query`
+
+`query` is passed directly to MongoDB as the filter for the collection read. Use standard MongoDB query operators.
+
+Ruby examples:
+
+```ruby
+# Equality
+query: { status: 'active' }
+
+# Ranges
+query: { created_at: { '$gte' => Time.parse('2025-01-01'), '$lt' => Time.parse('2025-02-01') } }
+
+# $in / $nin
+query: { type: { '$in' => %w[user admin] } }
+
+# Nested fields (dot-notation also supported in Mongo)
+query: { 'profile.country' => 'US' }
+
+# By ObjectId boundary (works great with _id partitions)
+query: { _id: { '$gt' => BSON::ObjectId.from_time(Time.utc(2024, 1, 1)) } }
+```
+
+CLI examples (JSON):
+
+```bash
+# Equality
+--query '{"status":"active"}'
+
+# Date/time range (ISO8601 strings your app can parse downstream)
+--query '{"created_at":{"$gte":"2025-01-01T00:00:00Z","$lt":"2025-02-01T00:00:00Z"}}'
+
+# Nested field
+--query '{"profile.country":"US"}'
+
+# IN list
+--query '{"type":{"$in":["user","admin"]}}'
+```
+
+Notes:
+- Ensure values are serializable; when using Ruby, you can pass native `Time`, `BSON::ObjectId`, etc.
+- Consider adding an appropriate index to match your `query` and pass `hint:` to force indexed scans when needed:
+
+```ruby
+Purplelight.snapshot(
+  client: client,
+  collection: 'events',
+  output: '/data/exports',
+  format: :jsonl,
+  query: { created_at: { '$gte' => Time.parse('2025-01-01') } },
+  hint: { created_at: 1 }
+)
+```
+
 Outputs files like:
 
 ```

data/lib/purplelight/snapshot.rb

@@ -81,7 +81,7 @@ module Purplelight
                  end
 
       manifest.configure!(collection: @collection.name, format: @format, compression: @compression, query_digest: query_digest, options: {
-        partitions: @partitions, batch_size: @batch_size, rotate_bytes: @rotate_bytes
+        partitions: @partitions, batch_size: @batch_size, rotate_bytes: @rotate_bytes, hint: @hint
       })
       manifest.ensure_partitions!(@partitions)
 
@@ -159,7 +159,7 @@ module Purplelight
     def read_partition(idx:, filter_spec:, queue:, batch_size:, manifest:)
       filter = filter_spec[:filter]
       sort = filter_spec[:sort] || { _id: 1 }
-      hint = filter_spec[:hint] || { _id: 1 }
+      hint = @hint || filter_spec[:hint] || { _id: 1 }
 
       # Resume from checkpoint if present
       checkpoint = manifest.partitions[idx] && manifest.partitions[idx]['last_id_exclusive']

data/lib/purplelight/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Purplelight
-  VERSION = "0.1.1"
+  VERSION = "0.1.2"
 end
 
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: purplelight
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Alexander Nicholson