{"id":19054466,"url":"https://github.com/datadog/sketches-js","last_synced_at":"2025-04-15T14:58:37.729Z","repository":{"id":37855162,"uuid":"298655695","full_name":"DataDog/sketches-js","owner":"DataDog","description":"TypeScript implementation of the distributed quantile sketch algorithm DDSketch","archived":false,"fork":false,"pushed_at":"2024-04-23T08:27:10.000Z","size":383,"stargazers_count":10,"open_issues_count":5,"forks_count":5,"subscribers_count":26,"default_branch":"master","last_synced_at":"2025-04-15T14:58:23.776Z","etag":null,"topics":["ddsketch","histogram","percentiles","quantiles","relative-error"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DataDog.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-09-25T18:54:03.000Z","updated_at":"2025-03-04T09:41:03.000Z","dependencies_parsed_at":"2024-04-23T10:13:14.718Z","dependency_job_id":null,"html_url":"https://github.com/DataDog/sketches-js","commit_stats":{"total_commits":51,"total_committers":6,"mean_commits":8.5,"dds":"0.17647058823529416","last_synced_commit":"222854e69a1437fbeb7e040bba8d65da73792fe8"},"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DataDog%2Fsketches-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DataDog%2Fsketches-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DataDog%2Fsketches-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DataDog%2Fsketches-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DataDog","download_url":"https://codeload.github.com/DataDog/sketches-js/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249094939,"owners_count":21211837,"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":["ddsketch","histogram","percentiles","quantiles","relative-error"],"created_at":"2024-11-08T23:38:29.774Z","updated_at":"2025-04-15T14:58:37.711Z","avatar_url":"https://github.com/DataDog.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# sketches-js\n\n![Continuous Integration](https://github.com/DataDog/sketches-js/workflows/Continuous%20Integration/badge.svg) [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n\nThis repo contains the TypeScript implementation of the distributed quantile sketch algorithm [DDSketch](http://www.vldb.org/pvldb/vol12/p2195-masson.pdf). DDSketch is mergeable, meaning that multiple sketches from distributed systems can be combined in a central node.\n\n## Installation\n\nThe package is under [@datadog/sketches-js](https://www.npmjs.com/package/@datadog/sketches-js) and can be installed through NPM or Yarn:\n\n```sh\n# NPM\nnpm install @datadog/sketches-js\n\n# Yarn\nyarn add @datadog/sketches-js\n```\n\nWhen using Protobuf serialization, the [protobufjs](https://www.npmjs.com/package/protobufjs) module must also be installed manually:\n\n```sh\n# NPM\nnpm install protobufjs\n\n# Yarn\nyarn add protobufjs\n```\n\n## Usage\n\n### Initialize a sketch\n\nTo initialize a sketch with the default parameters:\n\n```js\nimport { DDSketch } from '@datadog/sketches-js'; // or const { DDSketch } = require('@datadog/sketches-js');\nconst sketch = new DDSketch();\n```\n\n#### Modify the `relativeAccuracy`\n\nIf you want more granular control over how accurate the sketch's results will be, you can pass a `relativeAccuracy` parameter when initializing a sketch.\n\nWhereas other histograms use _rank error_ guarantees (i.e. retrieving the p99 of the histogram will give you a value between p98.9 and p99.1), DDSketch uses a _relative error_ guarantee (if the actual value at p99 is 100, the value will be between 99 and 101 for a `relativeAccuracy` of 0.01).\n\nThis property makes DDSketch especially useful for long-tailed distributions of data, like measurements of latency.\n\n```js\nimport { DDSketch } from '@datadog/sketches-js';\n\nconst sketch = new DDSketch({\n  relativeAccuracy: 0.01, // `relativeAccuracy` must be between 0 and 1\n});\n```\n\n### Add values to a sketch\n\nTo add a number to a sketch, call `sketch.accept(value)`. Both positive and negative numbers are supported.\n\n```js\nconst measurementOne = 1607374726;\nconst measurementTwo = 0;\nconst measurementThree = -3.1415;\n\nsketch.accept(measurementOne);\nsketch.accept(measurementTwo);\nsketch.accept(measurementThree);\n```\n\n### Retrieve measurements from the sketch\n\nTo retrieve measurements from a sketch, use `sketch.getValueAtQuantile(quantile)`. Any number between 0 and 1 (inclusive) can be used as a quantile.\n\nAdditionally, common summary statistics are available such as `sketch.min`, `sketch.max`, `sketch.sum`, and `sketch.count`:\n\n```js\nconst measurementOne = 1607374726;\nconst measurementTwo = 0;\nconst measurementThree = -3.1415;\n\nsketch.accept(measurementOne);\nsketch.accept(measurementTwo);\nsketch.accept(measurementThree);\n\nsketch.getValueAtQuantile(0)     // -3.1415\nsketch.getValueAtQuantile(0.5)   // 0\nsketch.getValueAtQuantile(0.99)  // 1607374726\nsketch.getValueAtQuantile(1)     // 1607374726\n\nsketch.min                       // -3.1415\nsketch.max                       // 1607374726\nsketch.count                     // 3\nsketch.sum                       // 1607374722.86\n```\n\n### Merge multiple sketches\n\nIndependent sketches can be merged together, provided that they were initialized with the same `relativeAccuracy`. This allows collecting and transmitting measurements in a distributed manner, and merging their results together while preserving the `relativeAccuracy` guarantee.\n\n```js\nimport { DDSketch } from '@datadog/sketches-js';\n\nconst sketch1 = new DDSketch();\nconst sketch2 = new DDSketch();\n\n[1,2,3,4,5].forEach(value =\u003e sketch1.accept(value));\n[6,7,8,9,10].forEach(value =\u003e sketch2.accept(value));\n\n// `sketch2` is merged into `sketch1`, without modifying `sketch2`\nsketch1.merge(sketch2);\n\nsketch1.getValueAtQuantile(1) // 10\n```\n\n## References\n* [DDSketch: A Fast and Fully-Mergeable Quantile Sketch with Relative-Error Guarantees](http://www.vldb.org/pvldb/vol12/p2195-masson.pdf). Charles Masson, Jee E. Rim and Homin K. Lee. 2019.\n* Java implementation: [https://github.com/DataDog/sketches-java](https://github.com/DataDog/sketches-java)\n* Go implementation: [https://github.com/DataDog/sketches-go](https://github.com/DataDog/sketches-go)\n* Python implementation: [https://github.com/DataDog/sketches-py](https://github.com/DataDog/sketches-py)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatadog%2Fsketches-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdatadog%2Fsketches-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatadog%2Fsketches-js/lists"}