Getting started with the Mach5 KQL Client

This guide demonstrates how to run a KQL query against a Mach5 mdx endpoint from Node.js. The CLI demonstrates how to

• configure the private @mach5-io/kql-client package,
• send queries through the client, and
• stream the Apache Arrow results back as JSON so you can hook the output into automation, observability, or reporting scripts.

Prerequisites

• Access to the https://github.com/mach5-io/mach5-sdk-ts repository. Contact the Mach5 Search Administrator to get access to this repository.
• Node.js 16+ (ensure node / npm are on your PATH). tsx is used to execute the TypeScript entry point without a build step.
• Mach5 deployment with an accessible mdx service endpoint.
• Access to @mach5-io/kql-client in npm.pkg.github.com. You need a GitHub token with read access to the package.

Setup

1. Enable the private registry for npm by appending your token to ~/.npmrc:

   cat <<'EOF' >> ~/.npmrc
   //npm.pkg.github.com/:_authToken=github_token_here
   @mach5-io:registry=https://npm.pkg.github.com/
   EOF
   

   Replace github_token_here with a token that can install @mach5-io/kql-client.

2. Clone the repository: https://github.com/mach5-io/mach5-sdk-ts. Change the working directory:

   cd mach5-sdk-ts/packages/kql-client/examples/kql-node-ts
   

3. Install dependencies in the mach5-sdk-ts/packages/kql-client/examples/kql-node-ts directory:

   npm install
   

4. Copy and edit the .env template:

   cp .env.example .env
   

   Then fill in the values:

   • MACH5_ENDPOINT: the base URL for your Mach5 mdx service (e.g., https://mdx.mach5.local:50561).
   • MACH5_KQL_QUERY: the KQL statement to execute (for example, tables | take 5).
   • MACH5_BEARER_TOKEN (optional): include this if your endpoint requires Authorization: Bearer headers.

Running queries

• Start the CLI with npm run dev (it runs tsx src/index.ts).
• The client prints Running query: ..., streams the Arrow record batches, and logs each row as a normalized JSON object.
• Once the stream completes, you’ll see the total batch and row counts on the final line.

Set MACH5_KQL_QUERY to any valid KQL command. The CLI can be rerun after updating .env or by overriding env vars inline, e.g.: MACH5_KQL_QUERY="MyTable | limit 10" npm run dev.

What the example shows

1. Client setup – instantiates @mach5-io/kql-client with the endpoint from MACH5_ENDPOINT.
2. Optional auth – includes a bearer token via metadata when MACH5_BEARER_TOKEN is present.
3. Streaming Arrow batches – iterates over for await (const table of result) to process each Apache Arrow table.
4. JSON normalization – converts Arrow vectors, nested records, and arrays to plain JSON so the logs are easy to consume.
5. Telemetry – reports the number of batches and rows processed before exiting.