Class Client

constructor

• new Client(baseUrl: string, options?: ClientOptions): Client

  Parameters

  • baseUrl: string
  • options: ClientOptions = {}

  Returns Client

ReadonlybaseUrl

ReadonlytimeoutMs

ReadonlyuserAgent

audit

• audit(
      options?: { decision?: AuditDecision; limit?: number },
  ): Promise<AuditPage>

  Read the decisions the engine recently made, newest first.

  Not served unless an operator started the engine with -audit-readers naming who may read it, because the record contains every caller's activity. An engine with nobody named answers 404 and a caller who is authenticated but not named gets 403, so handle both: this is one of the few calls that can fail for reasons that are nothing to do with the request.

  It is a bounded window rather than the whole record. An engine writing an audit file keeps everything there.

  Parameters

  • options: { decision?: AuditDecision; limit?: number } = {}

    • Optionaldecision?: AuditDecision

      Return only this decision. refused is the useful one.

    • Optionallimit?: number

      Most recent decisions to return, up to 200.

  Returns Promise<AuditPage>

cancelJob

• cancelJob(jobId: string): Promise<Job>

  Stop a running query. Idempotent.

  Parameters

  • jobId: string

  Returns Promise<Job>

compile

• compile(request: QueryRequest): Promise<Compiled>

  Return the SQL a request compiles to, without running it.

  A dry run is still governed: a request you may not run returns a refusal and no SQL, and the inspection is audited. It is a way to see what a query would do, not a way around the gate.

  Parameters

  • request: QueryRequest

  Returns Promise<Compiled>

diff

• diff(): Promise<Diff>

  Whether the last model reload moved a number.

  This compares the model being served against the one served before it, which is the comparison nobody can make from outside the process. An engine that has served only one model answers 404 as Refused, because that is a different answer from nothing having changed and only one of them is reassuring.

  Returns Promise<Diff>

dimensions

• dimensions(metric?: string): Promise<Dimension[]>

  Dimensions available for grouping and filtering.

  Parameters

  • Optionalmetric: string

    Restrict to dimensions valid for this metric, which is almost always what you want.

  Returns Promise<Dimension[]>

doctor

• doctor(): Promise<Diagnosis>

  Ask the warehouse whether the model is still true.

  Everything else validates the model against itself: the YAML parses, the joins resolve, the expressions compile. None of that notices that somebody dropped a column last Tuesday, and the first sign of that is usually a caller getting an error, which is the most expensive place to find it.

  Reports rather than refuses, so a rejection here means the check could not run. Read ok for the verdict and skipped for the case where nothing could be checked at all.

  Returns Promise<Diagnosis>

doctorHistory

• doctorHistory(): Promise<DoctorHistory>

  What the scheduled warehouse check has seen, oldest first.

  Drift is found by looking regularly, not by looking once, which is how "when did this start" stays answerable. An engine started without -doctor-every has nothing scheduled and answers 404 as Refused.

  Returns Promise<DoctorHistory>

explainPolicy

• explainPolicy(metric: string): Promise<PolicyExplanation>

  What you may read of a metric, and why.

  Answers "why can I not group by that column" without running a query and being denied. For the calling identity only, which is a security property rather than a limitation: an endpoint that reported another identity's access would publish the policy it was configured to enforce.

  Parameters

  • metric: string

    The qualified name, as metrics reports it.

  Returns Promise<PolicyExplanation>

health

• health(): Promise<Health>

  What this deployment enforces, including what it does not.

  Worth reading before trusting the layer with anything sensitive: enforcementNotes states the gaps in plain language.

  Returns Promise<Health>

job

• job(
      jobId: string,
      options?: { cursor?: string; pageSize?: number },
  ): Promise<Job>

  Poll a job and read one page of its rows.

  Parameters

  • jobId: string
  • options: { cursor?: string; pageSize?: number } = {}

  Returns Promise<Job>

metric

• metric(name: string): Promise<Metric>

  One metric's definition and the dimensions legal for it.

  Parameters

  • name: string

    Qualified as namespace.metric, or bare when unambiguous.

  Returns Promise<Metric>

metrics

• metrics(search?: string): Promise<Metric[]>

  Every metric this identity may read.

  Parameters

  • Optionalsearch: string

  Returns Promise<Metric[]>

modelVersion

• modelVersion(): Promise<string>

  The workspace digest currently served.

  Every query result carries this too. Two results with the same digest were produced by exactly the same definitions.

  Returns Promise<string>

namespaces

• namespaces(): Promise<Namespace[]>

  The namespaces in the workspace, their owners and availability.

  Returns Promise<Namespace[]>

policy

• policy(): Promise<Policy>

  What this engine enforces, and what it does not.

  Says nothing about who is allowed what. For that, and only about yourself, use explainPolicy.

  Returns Promise<Policy>

query

• query(request: QueryRequest): Promise<Result>

  Answer a question and return rows.

  Use run instead when the warehouse might be slow: this call holds the connection open for the whole query.

  Parameters

  • request: QueryRequest

  Returns Promise<Result>

  Throws

  The engine declined. Check err.retry before retrying.

reload

• reload(): Promise<ReloadStatus>

  Tell the engine to re-read its model source.

  Resolves to reading or already running. Both mean the caller got what they asked for; treating the second as a failure would retry a sync that is already under way.

  It carries no model, deliberately: this means "look now", not "install this". The engine already follows git, so the only thing this changes is the wait. A method that accepted a model would be a second way into production, one that skips the pull request, the checks and the diff that reports which numbers move.

  Needs the deploy:model scope, which read:model and run:query never imply.

  Resolving does not mean the new model is serving. A sync is not instant, and reporting a commit before the swap happened would be a claim a pipeline then asserts as fact. Poll health and read origin.commit to know when the new model is the one answering.

  An engine reading from a path has nothing to re-read and answers 404. A model that fails to load is not a failure of this call either: the engine keeps serving the previous one and says so in a 502. Both are Refused.

  Returns Promise<ReloadStatus>

run

• run(options: RunOptions): Promise<Result>

  Run a query that may take longer than an HTTP request should.

  Submits the query, polls until it finishes, collects every page and returns one result. A large BigQuery scan routinely outlives the default timeout of an agent framework, and a synchronous call that times out leaves the query running and billable with nobody reading it.

  The governance gate runs during submission, so a request this identity may not make throws immediately rather than after a wait.

  Parameters

  • options: RunOptions

  Returns Promise<Result>

runTests

• runTests(): Promise<TestReport>

  Assert what this model answers.

  validate says the model holds together and diff says a number changed. Neither says a number was ever right.

  Check withheld as well as ok. A credential without run:query cannot cause warehouse execution, so cases that would are withheld and counted rather than run or silently dropped, and a caller reading only ok would conclude a suite passed when half of it never ran.

  Returns Promise<TestReport>

submit

• submit(request: QueryRequest): Promise<Job>

  Start a query in the background and return immediately.

  The returned job already carries compiledSql, because compilation happened synchronously. A job coming back at all means the query was authorized, not merely accepted.

  Prefer run unless you need to do something else while it runs.

  Parameters

  • request: QueryRequest

  Returns Promise<Job>

wait

• wait(
      jobId: string,
      options?: { maxWaitMs?: number; pageSize?: number },
  ): Promise<Job>

  Poll until a job reaches a terminal state.

  Backs off from a fast first poll to a two second ceiling, so a query that finishes quickly is not delayed and a slow one is not hammered.

  On expiry the job is cancelled before throwing, so giving up here also stops the warehouse work.

  Parameters

  • jobId: string
  • options: { maxWaitMs?: number; pageSize?: number } = {}

  Returns Promise<Job>

StaticfromEnv

• fromEnv(urlVar?: string, tokenVar?: string, options?: ClientOptions): Client

  Build a client from environment variables.

  Keeps the token out of source and out of the process list, which is where a token passed as a command-line flag ends up.

  Parameters

  • urlVar: string = "SEMANTIC_URL"
  • tokenVar: string = "SEMANTIC_TOKEN"
  • options: ClientOptions = {}

  Returns Client