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.