@causa/workspace-google 1.4.0-beta.1 → 1.4.0-beta.3

package/README.md

@@ -60,7 +60,7 @@ Backfilling is supported when `google.pubSub` is set as the `events.broker`. Tem
 - As a raw URI, using the format `[[projects/<projectId>/]locations/<location>/]services/<name>/path-to-trigger`.
 - As a project-scoped trigger, using the format `<projectPath>#<triggerName>[?<options>]`. The referenced project must be of type `serviceContainer` with `google.cloudRun` as `serviceContainer.platform`. The HTTP path is read from `serviceContainer.triggers[<triggerName>].endpoint` (whose `type` must be `http`), and the `options` query string is forwarded as URL query parameters. The target Cloud Run service name defaults to `project.name`, and can be overridden by setting `google.cloudRun.eventBackfillServiceName`.
 
-When no source is specified, the default is to fetch events to backfill from the BigQuery dataset configured in `google.pubSub.bigQueryStorage`. A custom BigQuery table can also be set as source using the `bq://<projectId>.<datasetId>.<tableId>` format. It should have the `data` and `attributes` columns.
+When no source is specified, the default is to fetch events to backfill from the BigQuery dataset configured in `google.pubSub.bigQueryStorage`, once per Pub/Sub message ID. A custom BigQuery table can also be set as source using the `bq://<projectId>.<datasetId>.<tableId>` format. It should have the `data` and `attributes` columns.
 
 The Pub/Sub publish options used when backfilling can be tuned through `google.pubSub.backfillPublishOptions`, which exposes the `maxOutstandingBytes`, `maxOutstandingMessages`, `maxBytes`, `maxMessages`, and `maxMilliseconds` fields.
 
@@ -68,11 +68,13 @@ By default, project-scoped triggers send backfill events to the live Cloud Run s
 
 ### Querying
 
-This module implements the `DatabaseQueryRecords`, `ServiceContainerQueryLogs`, and `EventTopicQueryEvents` workspace functions, which expose read-only access to data stored in or emitted by deployed services:
+This module implements the `DatabaseQueryRecords`, `DatabaseCountRecords`, `ServiceContainerQueryLogs`, `EventTopicQueryEvents`, and `EventTopicCountEvents` workspace functions, which expose read-only access to data stored in or emitted by deployed services:
 
 - `DatabaseQueryRecords` is supported for the `google.spanner` and `google.firestore` engines. For Spanner, the function takes a database name and a SQL query, runs it on the configured Spanner instance, and returns the matching rows (capped to 100000). For Firestore, the query is the path to a single document, fetched from the default database (or the specified one). The document data is returned as a single-element array. An empty array is returned when the document does not exist.
+- `DatabaseCountRecords` is supported for the `google.spanner` engine. It counts the rows of the table in the schema's `googleSpannerTable` binding, in the database whose DDL creates it, or the one in the domain of the schema when several databases create a table with that name. Properties are read from the column named by their `googleSpannerColumn` extension, or from the column with the same name, and nested properties are read from JSON columns, where a value only equals a constant of the same JSON type.
 - `ServiceContainerQueryLogs` is supported when `serviceContainer.platform` is `google.cloudRun`. It queries Cloud Logging for log entries emitted by the service's Cloud Run revisions. By default, only the last hour of logs and up to 1 000 entries are returned.
-- `EventTopicQueryEvents` is supported when `events.broker` is `google.pubSub`, `events.format` is `json`, and `google.pubSub.bigQueryStorage.rawEventsDatasetId` is set. It reads events from the topic's BigQuery raw events table. Same defaults as for log queries: last hour and up to 1 000 events.
+- `EventTopicQueryEvents` is supported when `events.broker` is `google.pubSub`, `events.format` is `json`, and `google.pubSub.bigQueryStorage.rawEventsDatasetId` is set. It reads events from the topic's BigQuery raw events table, once per Pub/Sub message ID, as the BigQuery subscription may write a message several times. Same defaults as for log queries: last hour and up to 1 000 events.
+- `EventTopicCountEvents` is supported in the same cases as `EventTopicQueryEvents`. It counts the events published within the time range in the topic's BigQuery raw events table, whose `data` column should be of the `JSON` type, once per Pub/Sub message ID. A value only equals a constant of the same JSON type.
 
 ### Architecture graph
 
@@ -83,6 +85,20 @@ This module contributes to the architecture graph extracted by `cs graph extract
 
 Infrastructure nodes carry the Google Cloud resource they stand for in `data.resource`: its `type` (e.g. `pubsub.googleapis.com/Topic`), its `id`, i.e. its full resource name (or `idPrefix` when the full name is not known), and the `scope`, i.e. the project whose configuration should be used to render the identifier.
 
+When the graph is enriched with environment data, this module resolves the names of Cloud Tasks queues by listing the queues of the environment. Queues that cannot be resolved are removed from their nodes. This module's fetchers then:
+
+- read metrics of services, API routers, Pub/Sub topics and subscriptions, Cloud Tasks queues, and Spanner, Firestore, and BigQuery databases from Cloud Monitoring
+- add the `deployment` of Cloud Run services, and the `lastAttempt` and `nextRun` of Cloud Scheduler jobs. They describe services and jobs as they are when the graph is enriched, with a warning when they changed after `at`.
+- add `links` to the Google Cloud console for each resource
+- attach the alerts open in Cloud Monitoring to the nodes of their resources. Matching an alert to a node requires the condition of its policy to keep the labels making up the resource name (e.g. `project_id`, `location`, and `service_name`), along with `monitored_resource` when the metric is written against several resource types, like `logging.googleapis.com/log_entry_count`.
+- attach the open Error Reporting groups of Cloud Run services to their nodes, as alerts with the `error` severity. A group is open when it has occurrences during the last 30 days, and is not acknowledged, resolved, or muted.
+
+The requests and latencies of API routers are also grouped by the `node` the requests were routed to, by mapping the serverless network endpoint groups of their load balancers to Cloud Run services. They are listed using the Compute Engine API (`compute.networkEndpointGroups.list`) in the projects of the API routers.
+
+`GraphFetchEnvironmentMetricSeries` is implemented for the metrics read from Cloud Monitoring.
+
+Cloud Monitoring exposes complete data with a delay of a few minutes. Metrics, including their time series, are read over windows ending at most 5 minutes ago.
+
 ### Secrets backend
 
 This module implements the `google.secretManager` secret backend, allowing fetching secrets from the Google Secret Manager service. Here are some example of how secrets with the `google.secretManager` backend should be defined:

package/dist/functions/event-topic/count-events-bigquery.call.d.ts

@@ -0,0 +1,3 @@
+import type { RecordCounts } from '@causa/workspace-core';
+import type { EventTopicCountEventsForBigQuery } from './count-events-bigquery.js';
+export default function call(this: EventTopicCountEventsForBigQuery): Promise<RecordCounts>;

package/dist/functions/event-topic/count-events-bigquery.call.js

@@ -0,0 +1,75 @@
+import { BigQueryService } from '../../services/index.js';
+import { rawEventsTableName } from '../google-pubsub/index.js';
+/**
+ * Returns the function converting a JSON value to the type of the given value, without failing for other types.
+ *
+ * @param value The value to which the JSON value is compared.
+ * @returns The name of the BigQuery conversion function.
+ */
+function laxConversion(value) {
+    switch (typeof value) {
+        case 'string':
+            return 'LAX_STRING';
+        case 'number':
+            return 'LAX_FLOAT64';
+        case 'boolean':
+            return 'LAX_BOOL';
+    }
+}
+/**
+ * Builds the condition on the event payload, stored in the `data` JSON column, for a {@link RecordCondition}.
+ *
+ * @param condition The condition.
+ * @param addParam A function adding a parameter to the query, and returning its name.
+ * @returns The SQL condition.
+ */
+function sqlCondition(condition, addParam) {
+    const value = `data${condition.path.map((key) => `[${JSON.stringify(key)}]`).join('')}`;
+    switch (condition.operator) {
+        case 'isNull':
+            return `(${value} IS NULL OR JSON_TYPE(${value}) = 'null')`;
+        case 'isNotNull':
+            return `JSON_TYPE(${value}) != 'null'`;
+        case 'equals':
+            // The type is checked as lax conversions also convert values of other types, e.g. the string `"false"` to `FALSE`.
+            return `JSON_TYPE(${value}) = '${typeof condition.value}' AND ${laxConversion(condition.value)}(${value}) = @${addParam(condition.value)}`;
+    }
+}
+export default async function call() {
+    const googleConf = this._context.asConfiguration();
+    const projectId = googleConf.getOrThrow('google.project');
+    const rawEventsDatasetId = googleConf.getOrThrow('google.pubSub.bigQueryStorage.rawEventsDatasetId');
+    const tableId = `${projectId}.${rawEventsDatasetId}.${rawEventsTableName(this.topic)}`;
+    const names = Object.keys(this.filters);
+    const params = {
+        from: this.from.toISOString(),
+        to: this.to.toISOString(),
+    };
+    let paramCount = 0;
+    const addParam = (value) => {
+        const param = `p${paramCount++}`;
+        params[param] = value;
+        return param;
+    };
+    const counts = names.map((name, index) => {
+        const conditions = this.filters[name].map((c) => sqlCondition(c, addParam));
+        return `COUNTIF(${conditions.join(' AND ') || 'TRUE'}) AS f${index}`;
+    });
+    // Events written several times to the table by the BigQuery subscription are only counted once.
+    const query = `
+    WITH events AS (
+      SELECT data
+      FROM \`${tableId}\`
+      WHERE publish_time >= @from AND publish_time < @to
+      QUALIFY ROW_NUMBER() OVER (PARTITION BY message_id ORDER BY publish_time) = 1
+    )
+    SELECT ${['COUNT(*) AS total', ...counts].join(', ')}
+    FROM events`;
+    this._context.logger.debug(`Counting events in BigQuery:\n${query}`);
+    const bigQuery = this._context.service(BigQueryService).bigQuery;
+    const [[row]] = await bigQuery.query({ query, params });
+    return {
+        total: Number(row.total),
+        counts: Object.fromEntries(names.map((name, index) => [name, Number(row[`f${index}`])])),
+    };
+}

package/dist/functions/event-topic/count-events-bigquery.d.ts

@@ -0,0 +1,11 @@
+import { EventTopicCountEvents, type RecordCounts } from '@causa/workspace-core';
+/**
+ * Implements {@link EventTopicCountEvents} for Pub/Sub topics whose events are stored in BigQuery via a BigQuery
+ * subscription. The events are read from the dataset configured at `google.pubSub.bigQueryStorage.rawEventsDatasetId`,
+ * whose `data` column is expected to be of the `JSON` type.
+ * Events are counted once per Pub/Sub message ID, and the time range applies to their publish time.
+ */
+export declare class EventTopicCountEventsForBigQuery extends EventTopicCountEvents {
+    _call(): Promise<RecordCounts>;
+    _supports(): boolean;
+}

package/dist/functions/event-topic/count-events-bigquery.js

@@ -0,0 +1,19 @@
+import { callDeferred } from '@causa/workspace';
+import { EventTopicCountEvents, } from '@causa/workspace-core';
+/**
+ * Implements {@link EventTopicCountEvents} for Pub/Sub topics whose events are stored in BigQuery via a BigQuery
+ * subscription. The events are read from the dataset configured at `google.pubSub.bigQueryStorage.rawEventsDatasetId`,
+ * whose `data` column is expected to be of the `JSON` type.
+ * Events are counted once per Pub/Sub message ID, and the time range applies to their publish time.
+ */
+export class EventTopicCountEventsForBigQuery extends EventTopicCountEvents {
+    async _call() {
+        return await callDeferred(this, import.meta.url);
+    }
+    _supports() {
+        const conf = this._context.asConfiguration();
+        return (conf.get('events.broker') === 'google.pubSub' &&
+            conf.get('events.format') === 'json' &&
+            !!conf.get('google.pubSub.bigQueryStorage.rawEventsDatasetId'));
+    }
+}

package/dist/functions/event-topic/create-backfill-source-bigquery.call.js

@@ -34,6 +34,12 @@ export default async function call() {
     WHERE
       (${this.filter})`;
     }
+    if (!this.source) {
+        // Events written several times to the default storage by the BigQuery subscription are only backfilled once.
+        query += `
+    QUALIFY
+      ROW_NUMBER() OVER (PARTITION BY message_id ORDER BY publish_time) = 1`;
+    }
     this._context.logger.debug(`Creating BigQuery job from query '${query}'.`);
     const bigQuery = this._context.service(BigQueryService).bigQuery;
     const [job] = await bigQuery.createQueryJob(query);

package/dist/functions/event-topic/create-backfill-source-bigquery.d.ts

@@ -9,7 +9,7 @@ export declare const BIGQUERY_SOURCE_REGEX: RegExp;
  * Two cases are supported:
  * - The `source` is a `bq://<projectId>.<datasetId>.<tableId>` URI.
  * - The `source` is omitted and the broker is `google.pubSub` with `google.pubSub.bigQueryStorage.rawEventsDatasetId`
- *   configured: events are read from the default BigQuery storage for the topic.
+ *   configured: events are read from the default BigQuery storage for the topic, once per Pub/Sub message ID.
  *
  * The returned async iterable pages through the query results and yields each row as a {@link BackfillEvent}.
  */

package/dist/functions/event-topic/create-backfill-source-bigquery.js

@@ -10,7 +10,7 @@ export const BIGQUERY_SOURCE_REGEX = /^bq:\/\/(?<tableId>.+)$/;
  * Two cases are supported:
  * - The `source` is a `bq://<projectId>.<datasetId>.<tableId>` URI.
  * - The `source` is omitted and the broker is `google.pubSub` with `google.pubSub.bigQueryStorage.rawEventsDatasetId`
- *   configured: events are read from the default BigQuery storage for the topic.
+ *   configured: events are read from the default BigQuery storage for the topic, once per Pub/Sub message ID.
  *
  * The returned async iterable pages through the query results and yields each row as a {@link BackfillEvent}.
  */

package/dist/functions/event-topic/index.d.ts

@@ -8,5 +8,6 @@ export { EventTopicBrokerDeleteTriggerResourceForServiceAccount } from './broker
 export { EventTopicBrokerGetTopicIdForPubSub } from './broker-get-topic-id-pubsub.js';
 export { EventTopicBrokerPublishEventsForGoogle } from './broker-publish-events-google.js';
 export { EventTopicBrokerWaitForProcessingForPubSub } from './broker-wait-for-processing-pubsub.js';
+export { EventTopicCountEventsForBigQuery } from './count-events-bigquery.js';
 export { EventTopicCreateBackfillSourceForBigQuery } from './create-backfill-source-bigquery.js';
 export { EventTopicQueryEventsForBigQuery } from './query-events-bigquery.js';

package/dist/functions/event-topic/index.js

@@ -8,5 +8,6 @@ export { EventTopicBrokerDeleteTriggerResourceForServiceAccount } from './broker
 export { EventTopicBrokerGetTopicIdForPubSub } from './broker-get-topic-id-pubsub.js';
 export { EventTopicBrokerPublishEventsForGoogle } from './broker-publish-events-google.js';
 export { EventTopicBrokerWaitForProcessingForPubSub } from './broker-wait-for-processing-pubsub.js';
+export { EventTopicCountEventsForBigQuery } from './count-events-bigquery.js';
 export { EventTopicCreateBackfillSourceForBigQuery } from './create-backfill-source-bigquery.js';
 export { EventTopicQueryEventsForBigQuery } from './query-events-bigquery.js';

package/dist/functions/event-topic/query-events-bigquery.call.js

@@ -24,10 +24,12 @@ export default async function call() {
     if (this.filter) {
         conditions.push(`(${this.filter})`);
     }
+    // Events written several times to the table by the BigQuery subscription are only returned once.
     const query = `
     SELECT message_id, publish_time, data, attributes
     FROM \`${tableId}\`
     WHERE ${conditions.join(' AND ')}
+    QUALIFY ROW_NUMBER() OVER (PARTITION BY message_id ORDER BY publish_time) = 1
     ORDER BY publish_time ASC
     LIMIT ${limit}`;
     this._context.logger.debug(`Querying BigQuery for events:\n${query}`);

package/dist/functions/event-topic/query-events-bigquery.d.ts

@@ -2,6 +2,7 @@ import { EventTopicQueryEvents, type QueriedEvent } from '@causa/workspace-core'
 /**
  * Implements {@link EventTopicQueryEvents} for Pub/Sub topics whose events are stored in BigQuery via a BigQuery
  * subscription. The events are read from the dataset configured at `google.pubSub.bigQueryStorage.rawEventsDatasetId`.
+ * Events are returned once per Pub/Sub message ID.
  */
 export declare class EventTopicQueryEventsForBigQuery extends EventTopicQueryEvents {
     _call(): Promise<QueriedEvent[]>;

package/dist/functions/event-topic/query-events-bigquery.js

@@ -3,6 +3,7 @@ import { EventTopicQueryEvents, } from '@causa/workspace-core';
 /**
  * Implements {@link EventTopicQueryEvents} for Pub/Sub topics whose events are stored in BigQuery via a BigQuery
  * subscription. The events are read from the dataset configured at `google.pubSub.bigQueryStorage.rawEventsDatasetId`.
+ * Events are returned once per Pub/Sub message ID.
  */
 export class EventTopicQueryEventsForBigQuery extends EventTopicQueryEvents {
     async _call() {

package/dist/functions/google-app-check/generate-token.js

@@ -9,6 +9,7 @@ var __metadata = (this && this.__metadata) || function (k, v) {
 };
 import { CliCommand, CliOption } from '@causa/cli';
 import { callDeferred, WorkspaceFunction } from '@causa/workspace';
+import { PassArgumentsByReference } from '@causa/workspace/function-registry';
 import { AllowMissing } from '@causa/workspace/validation';
 import { IsString } from 'class-validator';
 import { appCheckCommandDefinition } from '../../cli/index.js';
@@ -48,6 +49,7 @@ If the Firebase app ID is not specified, it will:
 - If not present in the configuration, will be automatically looked up from the API.`,
         summary: 'Generates an AppCheck token.',
         outputFn: (token) => console.log(token),
-    })
+    }),
+    PassArgumentsByReference()
 ], GoogleAppCheckGenerateToken);
 export { GoogleAppCheckGenerateToken };

package/dist/functions/google-firebase-storage/merge-rules.js

@@ -9,6 +9,7 @@ var __metadata = (this && this.__metadata) || function (k, v) {
 };
 import { CliCommand } from '@causa/cli';
 import { WorkspaceFunction } from '@causa/workspace';
+import { PassArgumentsByReference } from '@causa/workspace/function-registry';
 import { AllowMissing } from '@causa/workspace/validation';
 import { IsBoolean } from 'class-validator';
 import { firebaseStorageCommandDefinition } from '../../cli/index.js';
@@ -67,6 +68,7 @@ GoogleFirebaseStorageMergeRules = __decorate([
 Input files are looked for in the workspace using the globs defined in google.firebaseStorage.securityRulesFiles.`,
         summary: 'Merge Firebase Storage security rules into a single file.',
         outputFn: ({ securityRuleFile }) => console.log(securityRuleFile),
-    })
+    }),
+    PassArgumentsByReference()
 ], GoogleFirebaseStorageMergeRules);
 export { GoogleFirebaseStorageMergeRules };

package/dist/functions/google-firestore/merge-rules.js

@@ -9,6 +9,7 @@ var __metadata = (this && this.__metadata) || function (k, v) {
 };
 import { CliCommand } from '@causa/cli';
 import { WorkspaceFunction } from '@causa/workspace';
+import { PassArgumentsByReference } from '@causa/workspace/function-registry';
 import { AllowMissing } from '@causa/workspace/validation';
 import { IsBoolean } from 'class-validator';
 import { firestoreCommandDefinition } from '../../cli/index.js';
@@ -67,6 +68,7 @@ GoogleFirestoreMergeRules = __decorate([
 Input files are looked for in the workspace using the globs defined in google.firestore.securityRulesFiles.`,
         summary: 'Merge Firestore security rules into a single file.',
         outputFn: ({ securityRuleFile }) => console.log(securityRuleFile),
-    })
+    }),
+    PassArgumentsByReference()
 ], GoogleFirestoreMergeRules);
 export { GoogleFirestoreMergeRules };

package/dist/functions/google-identity-platform/generate-custom-token.js

@@ -8,6 +8,7 @@ var __metadata = (this && this.__metadata) || function (k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 };
 import { callDeferred, WorkspaceFunction } from '@causa/workspace';
+import { PassArgumentsByReference } from '@causa/workspace/function-registry';
 import { AllowMissing } from '@causa/workspace/validation';
 import { IsObject, IsString } from 'class-validator';
 /**
@@ -17,7 +18,7 @@ import { IsObject, IsString } from 'class-validator';
  * If `google.firebase.adminServiceAccount` is set, the service account will be used to sign the token. Otherwise, an
  * attempt will be made to find a valid service account in the `google.project`.
  */
-export class GoogleIdentityPlatformGenerateCustomToken extends WorkspaceFunction {
+let GoogleIdentityPlatformGenerateCustomToken = class GoogleIdentityPlatformGenerateCustomToken extends WorkspaceFunction {
     /**
      * The ID of the user for which the custom token should be generated.
      */
@@ -32,7 +33,7 @@ export class GoogleIdentityPlatformGenerateCustomToken extends WorkspaceFunction
     _supports() {
         return true;
     }
-}
+};
 __decorate([
     IsString(),
     __metadata("design:type", String)
@@ -42,3 +43,7 @@ __decorate([
     AllowMissing(),
     __metadata("design:type", Object)
 ], GoogleIdentityPlatformGenerateCustomToken.prototype, "claims", void 0);
+GoogleIdentityPlatformGenerateCustomToken = __decorate([
+    PassArgumentsByReference()
+], GoogleIdentityPlatformGenerateCustomToken);
+export { GoogleIdentityPlatformGenerateCustomToken };

package/dist/functions/google-pubsub/write-topics.js

@@ -9,6 +9,7 @@ var __metadata = (this && this.__metadata) || function (k, v) {
 };
 import { WorkspaceFunction } from '@causa/workspace';
 import { EventTopicList, } from '@causa/workspace-core';
+import { PassArgumentsByReference } from '@causa/workspace/function-registry';
 import { CAUSA_FOLDER } from '@causa/workspace/initialization';
 import { AllowMissing } from '@causa/workspace/validation';
 import { IsBoolean } from 'class-validator';
@@ -34,7 +35,7 @@ export function rawEventsTableName(topic) {
  * topic configurations.
  * This function returns a partial configuration, such that it can be used as a processor.
  */
-export class GooglePubSubWriteTopics extends WorkspaceFunction {
+let GooglePubSubWriteTopics = class GooglePubSubWriteTopics extends WorkspaceFunction {
     tearDown;
     /**
      * Returns the path to the directory where Pub/Sub topic configurations should be written.
@@ -80,9 +81,13 @@ export class GooglePubSubWriteTopics extends WorkspaceFunction {
     _supports() {
         return true;
     }
-}
+};
 __decorate([
     IsBoolean(),
     AllowMissing(),
     __metadata("design:type", Boolean)
 ], GooglePubSubWriteTopics.prototype, "tearDown", void 0);
+GooglePubSubWriteTopics = __decorate([
+    PassArgumentsByReference()
+], GooglePubSubWriteTopics);
+export { GooglePubSubWriteTopics };

package/dist/functions/google-services/enable.js

@@ -9,6 +9,7 @@ var __metadata = (this && this.__metadata) || function (k, v) {
 };
 import { CliCommand } from '@causa/cli';
 import { callDeferred, WorkspaceFunction } from '@causa/workspace';
+import { PassArgumentsByReference } from '@causa/workspace/function-registry';
 import { AllowMissing } from '@causa/workspace/validation';
 import { IsBoolean } from 'class-validator';
 import { googleCommandDefinition } from '../../cli/index.js';
@@ -38,6 +39,7 @@ Required GCP services should be defined in the 'google.services' configuration.
 They will be enabled in the 'google.project' GCP project.`,
         summary: 'Enables the GCP services used by the current project.',
         outputFn: ({ services }) => console.log(services.join('\n')),
-    })
+    }),
+    PassArgumentsByReference()
 ], GoogleServicesEnable);
 export { GoogleServicesEnable };

package/dist/functions/google-spanner/count-records.call.d.ts

@@ -0,0 +1,16 @@
+import type { ObjectSchema, RecordCondition, RecordCounts } from '@causa/workspace-core';
+import type { DatabaseCountRecordsForSpanner } from './count-records.js';
+/**
+ * Builds the SQL query counting the rows of a table, and those matching each filter.
+ *
+ * @param table The name of the table.
+ * @param schema The schema persisted in the table.
+ * @param filters The conditions of each filter, in order.
+ * @returns The SQL query and its parameters. The counts are returned in the `total` column, and the `f<index>` column
+ *   for each filter.
+ */
+export declare function buildCountQuery(table: string, schema: ObjectSchema, filters: RecordCondition[][]): {
+    sql: string;
+    params: Record<string, string | number | boolean>;
+};
+export default function call(this: DatabaseCountRecordsForSpanner): Promise<RecordCounts>;

package/dist/functions/google-spanner/count-records.call.js

@@ -0,0 +1,120 @@
+import { splitSchemaPath } from '@causa/workspace-core/jsonschema';
+import { Spanner } from '@google-cloud/spanner';
+import { GoogleSpannerListDatabases } from './list-databases.js';
+import { SPANNER_ENGINE } from './query-records.js';
+import { resolveSpannerTable } from './resolve-table.js';
+/**
+ * Finds the database whose DDL creates a table, using {@link resolveSpannerTable}.
+ *
+ * @param context The {@link WorkspaceContext}.
+ * @param table The name of the table.
+ * @param schema The schema persisted in the table.
+ * @returns The ID of the database.
+ */
+async function findDatabase(context, table, schema) {
+    const [databases, domainPaths] = await Promise.all([
+        context.call(GoogleSpannerListDatabases, {}),
+        context.listDomainPaths(),
+    ]);
+    const { file } = splitSchemaPath(schema.path);
+    const resolution = resolveSpannerTable(databases, table, file, domainPaths);
+    switch (resolution.kind) {
+        case 'resolved':
+            return resolution.database.id;
+        case 'missing':
+            throw new Error(`No Spanner DDL creates the table '${table}'.`);
+        case 'ambiguous':
+            throw new Error(`The table '${table}' is created in several Spanner databases: ${resolution.candidates
+                .map(({ id }) => `'${id}'`)
+                .join(', ')}.`);
+    }
+}
+/**
+ * Returns the SQL expression reading the value at a path in the records of a schema.
+ *
+ * @param schema The schema persisted in the table.
+ * @param path The names of the properties leading to the value.
+ * @returns The SQL expression, and the JSON value when it reads a nested value from a JSON column.
+ */
+function valueExpression(schema, path) {
+    const [name, ...nested] = path;
+    const property = schema.properties.find((p) => p.name === name);
+    if (!property) {
+        throw new Error(`'${name}' is not a property of '${schema.name}'.`);
+    }
+    const columnExtension = property.extensions.googleSpannerColumn;
+    const column = typeof columnExtension?.name === 'string' ? columnExtension.name : name;
+    const expression = `\`${column}\``;
+    if (nested.length === 0) {
+        return { expression };
+    }
+    const json = `${expression}${nested.map((key) => `[${JSON.stringify(key)}]`).join('')}`;
+    return { expression: `JSON_VALUE(${json})`, json };
+}
+/**
+ * Builds the SQL query counting the rows of a table, and those matching each filter.
+ *
+ * @param table The name of the table.
+ * @param schema The schema persisted in the table.
+ * @param filters The conditions of each filter, in order.
+ * @returns The SQL query and its parameters. The counts are returned in the `total` column, and the `f<index>` column
+ *   for each filter.
+ */
+export function buildCountQuery(table, schema, filters) {
+    const params = {};
+    const condition = (c) => {
+        const { expression, json } = valueExpression(schema, c.path);
+        if (c.operator !== 'equals') {
+            return `${expression} ${c.operator === 'isNull' ? 'IS NULL' : 'IS NOT NULL'}`;
+        }
+        const param = `p${Object.keys(params).length}`;
+        if (!json) {
+            params[param] = c.value;
+            return `${expression} = @${param}`;
+        }
+        // Nested values are read as strings from JSON columns, and only match values of the same JSON type.
+        const type = `JSON_TYPE(${json}) = '${typeof c.value}'`;
+        if (typeof c.value === 'number') {
+            params[param] = c.value;
+            return `${type} AND SAFE_CAST(${expression} AS FLOAT64) = @${param}`;
+        }
+        params[param] = String(c.value);
+        return `${type} AND ${expression} = @${param}`;
+    };
+    const counts = filters.map((conditions, index) => `COUNTIF(${conditions.map(condition).join(' AND ') || 'TRUE'}) AS f${index}`);
+    const sql = `SELECT ${['COUNT(*) AS total', ...counts].join(', ')} FROM \`${table}\``;
+    return { sql, params };
+}
+export default async function call() {
+    const table = this.schema.databases.find((d) => d.engine === SPANNER_ENGINE)?.table;
+    if (!table) {
+        throw new Error(`The schema '${this.schema.name}' is not persisted in a Spanner table.`);
+    }
+    const names = Object.keys(this.filters);
+    const { sql, params } = buildCountQuery(table, this.schema, names.map((n) => this.filters[n]));
+    const databaseId = await findDatabase(this._context, table, this.schema);
+    const googleConf = this._context.asConfiguration();
+    const projectId = googleConf.getOrThrow('google.project');
+    const instanceName = googleConf.getOrThrow('google.spanner.instance.name');
+    this._context.logger.debug(`🗃️ Counting rows in Spanner database '${databaseId}' in instance '${instanceName}' (project '${projectId}'):\n${sql}`);
+    const spanner = new Spanner({ projectId });
+    let database;
+    try {
+        database = spanner.instance(instanceName).database(databaseId);
+        const [rows] = await database.run({
+            sql,
+            params,
+            json: true,
+            jsonOptions: { wrapNumbers: false },
+        });
+        const row = rows[0];
+        return {
+            total: Number(row.total),
+            counts: Object.fromEntries(names.map((name, index) => [name, Number(row[`f${index}`])])),
+        };
+    }
+    finally {
+        await database?.close();
+        spanner.close();
+    }
+}

package/dist/functions/google-spanner/count-records.d.ts

@@ -0,0 +1,15 @@
+import { DatabaseCountRecords, type RecordCounts } from '@causa/workspace-core';
+/**
+ * Implements {@link DatabaseCountRecords} for Spanner databases.
+ *
+ * The table is the one in the schema's `google.spanner` binding, in the database whose DDL creates it. When several
+ * databases create a table with that name, the one in the domain of the schema is chosen. The Spanner instance and GCP
+ * project are read from the workspace configuration.
+ *
+ * Properties are read from the column named by their `googleSpannerColumn` extension, or from the column with the same
+ * name. Nested properties are read from JSON columns.
+ */
+export declare class DatabaseCountRecordsForSpanner extends DatabaseCountRecords {
+    _call(): Promise<RecordCounts>;
+    _supports(): boolean;
+}

package/dist/functions/google-spanner/count-records.js

@@ -0,0 +1,21 @@
+import { callDeferred } from '@causa/workspace';
+import { DatabaseCountRecords } from '@causa/workspace-core';
+import { SPANNER_ENGINE } from './query-records.js';
+/**
+ * Implements {@link DatabaseCountRecords} for Spanner databases.
+ *
+ * The table is the one in the schema's `google.spanner` binding, in the database whose DDL creates it. When several
+ * databases create a table with that name, the one in the domain of the schema is chosen. The Spanner instance and GCP
+ * project are read from the workspace configuration.
+ *
+ * Properties are read from the column named by their `googleSpannerColumn` extension, or from the column with the same
+ * name. Nested properties are read from JSON columns.
+ */
+export class DatabaseCountRecordsForSpanner extends DatabaseCountRecords {
+    async _call() {
+        return await callDeferred(this, import.meta.url);
+    }
+    _supports() {
+        return this.engine === SPANNER_ENGINE;
+    }
+}

package/dist/functions/google-spanner/index.d.ts

@@ -1,5 +1,7 @@
+export { DatabaseCountRecordsForSpanner } from './count-records.js';
 export { ModelSchemaExtractDatabaseForGoogleSpanner } from './extract-database.js';
 export { ModelGenerateTypeScriptDecoratorsForGoogleSpanner } from './generate-typescript-decorators.js';
-export { GoogleSpannerListDatabases } from './list-databases.js';
+export { GoogleSpannerListDatabases, type SpannerDatabase, type SpannerTable, } from './list-databases.js';
 export { DatabaseQueryRecordsForSpanner } from './query-records.js';
+export { resolveSpannerTable, type SpannerTableResolution, } from './resolve-table.js';
 export { GoogleSpannerWriteDatabases } from './write-databases.js';

package/dist/functions/google-spanner/index.js

@@ -1,5 +1,7 @@
+export { DatabaseCountRecordsForSpanner } from './count-records.js';
 export { ModelSchemaExtractDatabaseForGoogleSpanner } from './extract-database.js';
 export { ModelGenerateTypeScriptDecoratorsForGoogleSpanner } from './generate-typescript-decorators.js';
-export { GoogleSpannerListDatabases } from './list-databases.js';
+export { GoogleSpannerListDatabases, } from './list-databases.js';
 export { DatabaseQueryRecordsForSpanner } from './query-records.js';
+export { resolveSpannerTable, } from './resolve-table.js';
 export { GoogleSpannerWriteDatabases } from './write-databases.js';

package/dist/functions/google-spanner/list-databases.d.ts

@@ -1,4 +1,21 @@
 import { WorkspaceFunction } from '@causa/workspace';
+/**
+ * A table created by a `CREATE TABLE` statement in a Spanner DDL file.
+ */
+export type SpannerTable = {
+    /**
+     * The name of the table.
+     */
+    readonly name: string;
+    /**
+     * The absolute path of the DDL file creating the table.
+     */
+    readonly file: string;
+    /**
+     * The line of the statement in the file.
+     */
+    readonly line: number;
+};
 /**
  * The definition of a Spanner database with its DDL statements.
  */
@@ -15,6 +32,10 @@ export type SpannerDatabase = {
      * The DDL statements for the database.
      */
     ddls: string[];
+    /**
+     * The tables created by the `CREATE TABLE` statements of the DDL files.
+     */
+    tables: SpannerTable[];
 };
 /**
  * A function that lists Spanner databases defined in the workspace, and returns their corresponding DDLs.
@@ -26,7 +47,7 @@ export declare class GoogleSpannerListDatabases extends WorkspaceFunction<Promis
      * End-of-the-line comments are removed, and statements are split using semicolons.
      *
      * @param path The path to the SQL file containing DDL statements.
-     * @returns The list of DDL statements.
+     * @returns The list of DDL statements, along with the file and the line at which each statement starts.
      */
     private parseDdlFile;
     _supports(): boolean;