Skip to content
Ruby gem for getting data from JSON streams based on various criteria (key, nesting level, etc)
Ruby Shell
Branch: master
Clone or download
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github/workflows Install yajl package Aug 21, 2019
bin Initial implementation; Support for getting objects based on nesting … May 28, 2016
ruby-devenv @ 97fdc8b Add ruby-devenv submodule Apr 4, 2017
spec Add doc of return enumerator feature; Add testcase for empty block Nov 24, 2018
.gitignore Ignore IntelliJ project files May 29, 2017
.gitmodules Add ruby-devenv submodule Apr 4, 2017
.rspec Add rspec config to print run test cases with color May 4, 2017
Gemfile Initial implementation; Support for getting objects based on nesting … May 28, 2016
Guardfile Adds Guard Sep 17, 2017
LICENSE.txt Initial implementation; Support for getting objects based on nesting … May 28, 2016 Switch CI to GH actions, remove travis build Aug 28, 2019
Rakefile Fix Rake require test and task order Apr 26, 2017
json-streamer.gemspec Update bundler version Aug 21, 2019


Ruby gem for getting data from JSON streams based on various criteria (key, nesting level, etc).

Status and support

  • ✔ stable
  • ✔ supported
  • ✖ no ongoing development

You are viewing the README of version v2.1.0. You can find other releases here.

Branch Status
Release Coverage Status Gem Version Total Downloads
Development Build Status Coverage Status

If you've tried JSON streaming with other Ruby libraries before (e.g. JSON::Stream, Yajl::FFI)

This gem will basically spare you the need to define your own callbacks (i.e. implement an actual JSON parser using start_object, end_object, key, value, etc.).

If you're new to this

Streaming is useful for

  • big files that do not fit in the memory (or you'd rather avoid the risk)
  • files read in chunks (e.g. arriving over network)
  • cases where you expect some issue with the file (e.g. losing connection to source, invalid data at some point) but would like to get as much data as possible anyway

This gem is aimed at making streaming as easy and convenient as possible.


Highly depends on the event generator. Out of the box the gem uses JSON::Stream. It was chosen because it's a pure Ruby parser with no runtime dependencies. You can use any custom event generator, such as Yajl::FFI which is dependent on the native YAJL library and is ~10 times faster. See the Custom event generators chapter.

I did not measure the performance of my implementation on top of these libraries.


The gem's single runtime dependency is JSON::Stream. It is only loaded if the default event generator is used.


Add this line to your application's Gemfile:

gem 'json-streamer'

And then execute:

$ bundle

Or install it yourself as:

$ gem install json-streamer


require 'json/streamer'

Passing IO upfront

Since v1.2.0

file_stream ='data.json', 'r')
chunk_size = 500 # defaults to 1000

streamer = Json::Streamer.parser(file_io: file_stream, chunk_size: chunk_size)

Get objects based on nesting level

# Level zero yields the full JSON, first level yields data within the JSON 1-by-1, etc.
streamer.get(nesting_level:1) do |object|
    p object


    "object1": "first_level_value",
    "object2": {}



Get data based on key

streamer.get(key:'desired_key') do |object|
    p object


    "obj1" : {
        "desired_key" : "value1"
    "desired_key" : "value2",
    "obj2" : {
        "desired_key" : {
            "desired_key" : "value3"


{"desired_key" => "value3"}

Skip values

streamer.get(nesting_level:1, yield_values:false) do |object|
    p object


    "obj1" : {},
    "key" : "value"



Symbolize keys

Since v1.3.0

streamer.get(nesting_level:0, symbolize_keys: true) do |object|
    p object


    "obj1" : {"key" : "value"}



Passing IO later (EventMachine-style)

# Get a JsonStreamer object that provides access to the parser
# but does not start processing immediately
streamer = Json::Streamer.parser

streamer.get(nesting_level:1) do |object|
    p object

Then later in your EventMachine handler:

def receive_data(data)
    streamer << data

Custom event generators

Since v2.1.0

require "yajl/ffi"


Any parser can be used that provides the right events. The gem is tested with Yajl::FFI and JSON::Stream.

Custom yield conditions

Since v2.0.0

Custom conditions provide ultimate control over what to yield.

The Conditions API exposes 3 callbacks:

  • yield_value
  • yield_array
  • yield_object

Each of them may be redefined. They are called once the corresponding data (value, array or object) is available. They should return whether the data should be yielded for the outside. They receive the data and the aggregator as parameters.

The aggregator exposes data about the current state of the partly parsed JSON such as:

  • level - current level
  • key - current key
  • value - current value
  • key_for_level(level) - key for custom level
  • value_for_level(level) - value for custom level
  • get - the raw data (in a custom format)

Example usage (inspired by this issue):

conditions =
conditions.yield_value = ->(aggregator:, value:) { false }
conditions.yield_array = ->(aggregator:, array:) { false }
conditions.yield_object = lambda do |aggregator:, object:|
    aggregator.level.eql?(2) && aggregator.key_for_level(1).eql?('items1')

streamer.get_with_conditions(conditions) do |object|
    p object


  "other": "stuff",
  "items1": [
      "key1": "value"
      "key2": "value"
  "items2": [
      "key3": "value"
      "key4": "value"



Get an Enumerable when not passing a block

Since v2.1.0

When not passed a block both get and get_with_conditions return an enumerator of the requested objects. When passed a block they return an empty enumerator. This means that when not passed a block the requested objects will accumulate in memory.

Without block

objects = streamer.get(nesting_level:1)
p objects


    "object1": "first_level_value",
    "object2": {}


["first_level_value", {}]

With block

unyielded_objects = streamer.get(nesting_level:1) { |object| do_something(object) }
p unyielded_objects


    "object1": "first_level_value",
    "object2": {}



Other usage information

Check the unit tests for more examples (spec/streamer_spec.rb).

One streamer object handles one set of conditions. For multiple conditions create multiple streamers. For more details see this discussion.

Deprecated API

Pre v1.2.0

This functionality is deprecated but kept for compatibility reasons.

# Same as Json::Streamer.parser
streamer =
# Same as streamer << data
streamer.parser << data

Contribution and feedback

This project is built around known use-cases. If you have one that isn't covered don't hesitate to open an issue and start a discussion.

Bug reports and pull requests are welcome on GitHub at This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.


This project follows C-Hive guides for code style, way of working and other development concerns.


The gem is available as open source under the terms of the MIT License.

You can’t perform that action at this time.