Build Status

Zn is a tool to search and correlate data sources (JSON files for now).



$ git clone https://github.com/lpadukana/zn
$ bin/setup
$ bin/install


$ docker run -it latheeshp/zn:latest

Note: For latest changes, please use exe/zn instead of depending on the installed version.


This tool depends on an index to understand the relationship between datasets. An example is available at spec/fixtures/starwars/index.yml. In this case, this file defines how people.json, planets.json and robots.json are related.

Discovering Datasets

$ export ZN_CONFIG_FILE=spec/fixtures/starwars/index.yml

$ zn list-datasets

Note: config file can also be passed in as --config-file spec/fixtures/starwars/index.yml

Discovering Keys

$ export ZN_CONFIG_FILE=spec/fixtures/starwars/index.yml

$ zn list-keys --dataset robots

Search Examples

$ export ZN_CONFIG_FILE=spec/fixtures/starwars/index.yml

$ zn search --dataset robots --key id --value r2

$ zn search --dataset people --key name --value Kenobi
{"id":"obi","name":"Obi Wan Kenobi","planet_id":"ste"}

# --exact can be used to search for exact values
$ zn search --exact --dataset people --key name --value 'Obi Wan Kenobi'
{"id":"obi","name":"Obi Wan Kenobi","planet_id":"ste"}

Search and Associate Example

$ export ZN_CONFIG_FILE=spec/fixtures/starwars/index.yml

$ zn search --dataset robots --key id --value r2 | zn associate --dataset robots
{"id":"r2","name":"R2-D2","owner_id":"obi","owner":{"id":"obi","name":"Obi Wan Kenobi","planet_id":"ste"}}

$ zn search --dataset people --key name --value Kenobi | zn associate --dataset people
{"id":"obi","name":"Obi Wan Kenobi","planet_id":"ste","robots":[{"id":"r2","name":"R2-D2","owner_id":"obi"},{"id":"c3po","name":"C-3PO","owner_id":"obi"}],"home_planet":{"id":"ste","name":"Stewjon"}}

Search, Associate and Pretty-print Example

$ export ZN_CONFIG_FILE=spec/fixtures/starwars/index.yml

$ zn search --dataset people --key name --value Kenobi | zn associate --dataset people | zn prettify-json
  "id": "obi",
  "name": "Obi Wan Kenobi",
  "planet_id": "ste",
  "robots": [
      "id": "r2",
      "name": "R2-D2",
      "owner_id": "obi"
      "id": "c3po",
      "name": "C-3PO",
      "owner_id": "obi"
  "home_planet": {
    "id": "ste",
    "name": "Stewjon"

Zendesk Examples to Try

$ export ZN_CONFIG_FILE=spec/fixtures/zendesk/index.yml

$ zn list-datasets
$ zn list-keys --dataset users
$ zn list-keys --dataset tickets
$ zn list-keys --dataset organizations
$ zn search --dataset users --key _id --value 10 | zn associate --dataset users | zn prettify-json
$ zn search --dataset tickets --key subject --value Australia | zn associate --dataset tickets | zn prettify-json
$ zn search --dataset organizations --key name --value Qualitern | zn associate --dataset organizations | zn prettify-json
$ zn search --dataset users --key _id --value 1 | wc -l
$ zn search --exact --dataset users --key _id --value 1 | wc -l



$ bin/rspec-test

Style Checks

$ bin/style-check

Smoke Tests

$ bin/smoke-test


After checking out the repo, run bin/setup to install dependencies. Then, run bin/test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bin/install. To release a new version, update the version number in version.rb, and then run bin/release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.


Bug reports and pull requests are welcome on GitHub at https://github.com/lpadukana/zn.


Available as open source under the terms of the MIT License.