{"id":13795564,"url":"https://github.com/andremleblanc/druiddb-ruby","last_synced_at":"2025-10-06T09:31:26.705Z","repository":{"id":62557521,"uuid":"96575282","full_name":"andremleblanc/druiddb-ruby","owner":"andremleblanc","description":"Ruby client for Druid using the Kafka Indexing Service","archived":false,"fork":false,"pushed_at":"2017-10-19T19:35:24.000Z","size":85538,"stargazers_count":5,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-05-14T02:02:13.344Z","etag":null,"topics":["druid","ruby","ruby-on-rails","timeseries-database"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/andremleblanc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-07-07T20:44:23.000Z","updated_at":"2022-08-03T20:34:50.000Z","dependencies_parsed_at":"2022-11-03T06:30:27.427Z","dependency_job_id":null,"html_url":"https://github.com/andremleblanc/druiddb-ruby","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andremleblanc%2Fdruiddb-ruby","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andremleblanc%2Fdruiddb-ruby/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andremleblanc%2Fdruiddb-ruby/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andremleblanc%2Fdruiddb-ruby/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/andremleblanc","download_url":"https://codeload.github.com/andremleblanc/druiddb-ruby/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":235517883,"owners_count":19002916,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["druid","ruby","ruby-on-rails","timeseries-database"],"created_at":"2024-08-03T23:00:58.729Z","updated_at":"2025-10-06T09:31:26.297Z","avatar_url":"https://github.com/andremleblanc.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# druiddb-ruby\n\n[![Build Status](https://travis-ci.org/andremleblanc/druiddb-ruby.svg?branch=master)](https://travis-ci.org/andremleblanc/druiddb-ruby)\n[![Gem Version](https://badge.fury.io/rb/druiddb.svg)](https://badge.fury.io/rb/druiddb)\n[![Code Climate](https://codeclimate.com/github/andremleblanc/druiddb-ruby/badges/gpa.svg)](https://codeclimate.com/github/andremleblanc/druiddb-ruby)\n[![Dependency Status](https://gemnasium.com/badges/github.com/andremleblanc/druiddb-ruby.svg)](https://gemnasium.com/github.com/andremleblanc/druiddb-ruby)\n\nThis documentation is intended to be a quick-start guide, not a comprehensive\nlist of all available methods and configuration options. Please look through\nthe source for more information; a great place to get started is `DruidDB::Client`\nand the `DruidDB::Query` modules as they expose most of the methods on the client.\n\nThis guide assumes a significant knowledge of Druid, for more info:\nhttp://druid.io/docs/latest/design/index.html\n\n## What Does it Do\n\ndruiddb-ruby provides a client for your Ruby application to push data to Druid leveraging the [Kafka Indexing Service](http://druid.io/docs/latest/development/extensions-core/kafka-ingestion.html). The client also provides an interface for querying and performing management tasks. It will automatically find and connect to Kafka and the Druid nodes through ZooKeeper, which means you only need to provide the ZooKeeper host and it will find everything else.\n\n## Install\n\n```bash\n$ gem install druiddb\n```\n\n## Usage\n\n### Creating a Client\n```ruby\nclient = DruidDB::Client.new()\n```\n*Note:* There are many configuration options, please take a look at\n`DruidDB::Configuration` for more details.\n\n### Writing Data\n\n#### Kafka Indexing Service\nThis gem leverages the [Kafka Indexing Service](http://druid.io/docs/latest/development/extensions-core/kafka-ingestion.html) for ingesting data. The gem pushes datapoints onto Kafka topics (typically named after the datasource). You can also use the gem to upload an ingestion spec, which is needed for Druid to consume the Kafka topic.\n\nThis repo contains a `docker-compose.yml` build that may help bootstrap development with Druid and the Kafka Indexing Service. It's what we use for integration testing.\n\n#### Submitting an Ingestion Spec\n\n```ruby\npath = 'path/to/spec.json'\nclient.submit_supervisor_spec(path)\n```\n\n####  Writing Datapoints\n```ruby\ntopic_name = 'foo'\ndatapoint = {\n  timestamp: Time.now.utc.iso8601,\n  foo: 'bar',\n  units: 1\n}\nclient.write_point(topic_name, datapoint)\n```\n\n### Reading Data\n\n#### Querying\n```ruby\nclient.query(\n  queryType: 'timeseries',\n  dataSource: 'foo',\n  granularity: 'day',\n  intervals: Time.now.utc.advance(days: -30) + '/' + Time.now.utc.iso8601,\n  aggregations: [{ type: 'longSum', name: 'baz', fieldName: 'baz' }]\n)\n```\nThe `query` method POSTs the query to Druid; for information on\nquerying Druid: http://druid.io/docs/latest/querying/querying.html. This is\nintentionally simple to allow all current features and hopefully all future\nfeatures of the Druid query language without updating the gem.\n\n##### Fill Empty Intervals\n\nCurrently, Druid will not fill empty intervals for which there are no points. To\naccommodate this need until it is handled more efficiently in Druid, use the\nexperimental `fill_value` feature in your query. This ensure you get a result\nfor every interval in intervals.\n\nThis has only been tested with 'timeseries' and single-dimension 'groupBy'\nqueries with simple granularities.\n\n```ruby\nclient.query(\n  queryType: 'timeseries',\n  dataSource: 'foo',\n  granularity: 'day',\n  intervals: Time.now.utc.advance(days: -30) + '/' + Time.now.utc.iso8601,\n  aggregations: [{ type: 'longSum', name: 'baz', fieldName: 'baz' }],\n  fill_value: 0\n)\n```\n\n### Management\nList datasources.\n```ruby\nclient.list_datasources\n```\n\nList supervisor tasks.\n```ruby\nclient.supervisor_tasks\n```\n\n## Development\n\n### Docker Compose\nThis project uses docker-compose to provide a development environment.\n\n1. git clone the project\n2. cd into project\n3. `docker-compose up` - this will download necessary images and run all dependencies in the foreground.\n\nWhen changes are made to the project, rebuild the Docker image with:\n\n```shell\n$ docker build -t \u003csome_tag\u003e .\n```\n\nWhere `\u003csome_tag\u003e` is something like `druiddb-ruby`.\n\nTo interact with the newly changed project, run it with:\n\n```shell\n$ docker run -it --network=druiddbruby_druiddb \u003csome_tag\u003e \u003csome_command\u003e\n```\nWhere `\u003csome_command\u003e` is a shell command that can be run on the docker image (i.e. `bash` or anything in the `bin` folder)\n\n### Metabase\n\nViewing data in the database can be a bit annoying, use a tool like [Metabase](https://github.com/metabase/metabase) makes this much easier and is what I personally do when developing.\n\n## Testing\n\nTesting is run utilizing the docker-compose environment.\n\n1. `docker-compose up`\n2. `docker run -it --network=druiddbruby_druiddb \u003csome_tag\u003e bin/run_tests.sh`\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandremleblanc%2Fdruiddb-ruby","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fandremleblanc%2Fdruiddb-ruby","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandremleblanc%2Fdruiddb-ruby/lists"}