cloudflare/src/resources/logs/log-explorer/query.ts

The official TypeScript library for the Cloudflare API

// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.

import { APIResource } from '../../../core/resource';
import { CloudflareError } from '../../../core/error';
import { PagePromise, SinglePage } from '../../../core/pagination';
import { type Uploadable } from '../../../core/uploads';
import { buildHeaders } from '../../../internal/headers';
import { RequestOptions } from '../../../internal/request-options';
import { path } from '../../../internal/utils/path';

export class BaseQuery extends APIResource {
  static override readonly _key: readonly ['logs', 'logExplorer', 'query'] = Object.freeze([
    'logs',
    'logExplorer',
    'query',
  ] as const);

  /**
   * Run a SQL query against account or zone-level datasets.
   *
   * Timestamp fields are RFC3339 strings. Filter with: WHERE {timestamp_field} >=
   * now() - INTERVAL '30' DAY WHERE {timestamp_field} >= '2026-04-01T00:00:00Z'
   * WHERE {timestamp_field} BETWEEN '2026-04-01T00:00:00Z' AND
   * '2026-04-30T23:59:59Z'
   *
   * List configured account or zone datasets to see enabled account or zone-level
   * datasets. Zone-level datasets will not appear here. List available account or
   * zone datasets to inspect their schemas and timestamp fields.
   *
   * For more information about the datasets, and the meaning of each field, check
   * out https://developers.cloudflare.com/logs/logpush/logpush-job/datasets/
   *
   * @example
   * ```ts
   * // Automatically fetches more pages as needed.
   * for await (const querySqlResponse of client.logs.logExplorer.query.sql(
   *   fs.createReadStream('path/to/file'),
   *   { account_id: 'account_id' },
   * )) {
   *   // ...
   * }
   * ```
   */
  sql(
    body: Uploadable,
    params: QuerySqlParams,
    options?: RequestOptions,
  ): PagePromise<QuerySqlResponsesSinglePage, QuerySqlResponse> {
    const { account_id, zone_id } = params;
    if (!account_id && !zone_id) {
      throw new CloudflareError('You must provide either account_id or zone_id.');
    }
    if (account_id && zone_id) {
      throw new CloudflareError('You cannot provide both account_id and zone_id.');
    }
    const { accountOrZone, accountOrZoneId } =
      account_id ?
        {
          accountOrZone: 'accounts',
          accountOrZoneId: account_id,
        }
      : {
          accountOrZone: 'zones',
          accountOrZoneId: zone_id,
        };
    return this._client.getAPIList(
      path`/${accountOrZone}/${accountOrZoneId}/logs/explorer/query/sql`,
      SinglePage<QuerySqlResponse>,
      {
        body: body,
        method: 'post',
        ...options,
        headers: buildHeaders([{ 'Content-Type': 'text/plain' }, options?.headers]),
      },
    );
  }
}
export class Query extends BaseQuery {}

export type QuerySqlResponsesSinglePage = SinglePage<QuerySqlResponse>;

export type QuerySqlResponse = { [key: string]: unknown };

export interface QuerySqlParams {
  /**
   * Path param: The Account ID to use for this endpoint. Mutually exclusive with the
   * Zone ID.
   */
  account_id?: string;

  /**
   * Path param: The Zone ID to use for this endpoint. Mutually exclusive with the
   * Account ID.
   */
  zone_id?: string;
}

export declare namespace Query {
  export {
    type QuerySqlResponse as QuerySqlResponse,
    type QuerySqlResponsesSinglePage as QuerySqlResponsesSinglePage,
    type QuerySqlParams as QuerySqlParams,
  };
}