{"id":17105375,"url":"https://github.com/kffl/pinot-client-node","last_synced_at":"2025-10-13T16:07:03.637Z","repository":{"id":36963007,"uuid":"497341041","full_name":"kffl/pinot-client-node","owner":"kffl","description":"Node.js client library for Apache Pinot  :wine_glass:, a realtime distributed OLAP datastore","archived":false,"fork":false,"pushed_at":"2023-09-04T07:49:17.000Z","size":178,"stargazers_count":8,"open_issues_count":6,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-26T19:11:11.134Z","etag":null,"topics":["apache-pinot","database-client","nodejs","olap","pinot","pinot-client"],"latest_commit_sha":null,"homepage":"https://kffl.github.io/pinot-client-node/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kffl.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-05-28T14:28:17.000Z","updated_at":"2024-11-17T17:07:11.000Z","dependencies_parsed_at":"2023-02-12T21:16:06.179Z","dependency_job_id":null,"html_url":"https://github.com/kffl/pinot-client-node","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kffl%2Fpinot-client-node","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kffl%2Fpinot-client-node/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kffl%2Fpinot-client-node/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kffl%2Fpinot-client-node/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kffl","download_url":"https://codeload.github.com/kffl/pinot-client-node/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247966899,"owners_count":21025675,"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":["apache-pinot","database-client","nodejs","olap","pinot","pinot-client"],"created_at":"2024-10-14T15:41:47.580Z","updated_at":"2025-10-13T16:06:58.602Z","avatar_url":"https://github.com/kffl.png","language":"TypeScript","readme":"# Node.js client library for Apache Pinot :wine_glass:\n\n[![CI Workflow](https://github.com/kffl/pinot-client-node/actions/workflows/ci.yml/badge.svg)](https://github.com/kffl/pinot-client-node/actions/workflows/ci.yml)\n[![NPM version](https://img.shields.io/npm/v/pinot-client.svg?style=flat)](https://www.npmjs.com/package/pinot-client)\n[![NPM downloads](https://img.shields.io/npm/dm/pinot-client.svg?style=flat)](https://www.npmjs.com/package/pinot-client)\n[![Known Vulnerabilities](https://snyk.io/test/github/kffl/pinot-client-node/badge.svg)](https://snyk.io/test/github/kffl/pinot-client-node)\n\nJavaScript client library for connecting to and querying Apache Pinot :wine_glass:, a realtime distributed OLAP datastore.\n\n[GitHub Repo](https://github.com/kffl/pinot-client-node), [TypeDoc Reference](https://kffl.github.io/pinot-client-node/), [npm Package](https://www.npmjs.com/package/pinot-client)\n\n## Features\n\n-   Implements a controller-based broker selector that periodically updates the table-to-broker mapping via the controller API.\n-   Provides TypeScript definitions of broker responses (Pinot query results).\n-   Has 100% test coverage.\n\n## Quick start\n\nStart a development Pinot cluster with `baseballStats` demo data:\n\n```bash\ndocker run \\\n    -p 9000:9000 -p 8000:8000 \\\n    apachepinot/pinot:0.9.3 QuickStart \\\n    -type batch\n```\n\n### Installation\n\n```\nnpm install pinot-client\n```\n\nor\n\n```\nyarn add pinot-client\n```\n\n### Creating a connection to a Pinot cluster\n\nWith a simple broker selector (that chooses randomly between the provided brokers upon each query):\n\n```typescript\nimport { ConnectionFactory } from \"pinot-client\";\n\nconst connection = ConnectionFactory.fromHostList([\"localhost:8000\"]);\n```\n\nWith a controller-based broker selector (that maintains a periodically updated table-to-broker mapping obtained via controller API):\n\n```typescript\nimport { ConnectionFactory } from \"pinot-client\";\n\nconst connection = await ConnectionFactory.fromController(\"localhost:9000\");\n```\n\n### Querying Pinot\n\n```typescript\nconst r = await connection.execute(\n    \"baseballStats\", // table name\n    \"select league, sum(hits) as hits from baseballStats group by league order by hits desc\" // SQL query\n);\n\nconsole.log(`Scanned ${r.numDocsScanned} docs in ${r.timeUsedMs}ms`);\nconsole.log(\"Results:\");\nconsole.log(r.resultTable.dataSchema.columnNames.join(\"\\t\"));\nr.resultTable.rows.forEach((row) =\u003e {\n    console.log(row.join(\"\\t\"));\n});\n```\n\nOutput:\n\n```\nScanned 97889 docs in 8ms\nleague  hits\nNL      1890198\nAL      1650039\nAA      88730\nNA      24549\nFL      21105\nPL      10523\nUA      7457\n```\n\n## Usage\n\n### `fromHostList()` and `fromController()` options\n\n`ConnectionFactory.fromHostList()` may optionally take as a second parameter an object with the following keys:\n\n-   `logger`: a logger instance conforming to the standard Log4j interface w/ .child() method (i.e. pino, winston or log4js)\n-   `brokerReqHeaders`: additional HTTP headers (object key: value) to include in broker query API requests\n-   `customHttpClient`: a custom HTTP client implementation\n\non top of that, `ConnectionFactory.fromController()` options may include two additional keys:\n\n-   `controllerReqHeaders`: additional HTTP headers (object key: value) to include in controller API requests\n-   `brokerUpdateFreqMs`: wait time in milliseconds between table-to-broker mapping refreshes\n\nExample usage:\n\n```typescript\nconst options = {\n    brokerReqHeaders: {\n        Authorization: \"Basic asdf123\",\n    },\n    controllerReqHeaders: {\n        Authorization: \"Basic xyz123\",\n    },\n    brokerUpdateFreqMs: 500,\n};\n\nconst connection = await ConnectionFactory.fromController(\"localhost:9000\", options);\n```\n\n### Using a custom logger\n\n```typescript\n// let's use pino (not to be confused with pinot) as an example logger\nimport * as pino from \"pino\";\n\nconst pinoInstance = pino({ level: \"debug\" });\nconst childLogger = pinoInstance.child({ lib: \"pinot-client\" });\n\nconst options = {\n    logger: childLogger,\n};\n\nconst connection = await ConnectionFactory.fromController(\"localhost:9000\", options);\n```\n\n### Using a custom HTTP client\n\nBy default `pinot-client` uses `undici` for performing HTTP requests against Pinot Borkers and Controllers. A custom `HttpClient` interface implementation (containing POST and GET methods) can be provided instead via the `customHttpClient` options key:\n\n```typescript\n\nconst myClient: HttpClient = {\n    get: async function \u003cT\u003e(url: string, options: { headers: Record\u003cstring, string\u003e }) {\n        const { statusCode, parsedBody } = await otherHTTPClientLib\u003cT\u003e(url, ...);\n        // data is of type T\n        return { status: statusCode, data: parsedBody };\n    },\n    post: async function \u003cT\u003e(url: string, data: object, options: { headers: Record\u003cstring, string\u003e }) {\n        const { statusCode, parsedBody } = await otherHTTPClientLib\u003cT\u003e(url, ...);\n        // data is of type T\n        return { status: statusCode, data: parsedBody };\n    },\n};\n\nconst options = {\n    customHttpClient: myClient,\n}\n\nconst c = await ConnectionFactory.fromController(\"http://localhost:9000\", options);\n\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkffl%2Fpinot-client-node","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkffl%2Fpinot-client-node","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkffl%2Fpinot-client-node/lists"}