@causa/workspace-google 0.15.0 → 0.17.0

package/README.md

@@ -55,10 +55,21 @@ The following emulators are implemented:
 
 ### Backfilling
 
-Backfilling is supported when `google.pubSub` is set as the `events.broker`. Temporary triggers can be created for Cloud Run services, by referencing them using the format `[[projects/<projectId>/]locations/<location>/]services/<name>/path-to-trigger`.
+Backfilling is supported when `google.pubSub` is set as the `events.broker`. Temporary triggers can be created for Cloud Run services in two ways:
+
+- 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.
 
+### 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:
+
+- `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.
+- `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.
+
 ### 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/configurations/generated.d.ts

@@ -67,6 +67,12 @@ export declare class GoogleCloudRun {
      * The Docker repository where Cloud Run containers should be uploaded.
      */
     readonly dockerRepository?: string;
+    /**
+     * For `serviceContainer` projects deployed on Cloud Run, the name of the Cloud Run service that receives
+     * events during a backfill targeting a project-scoped trigger. Defaults to the project's name
+     * (`project.name`) when unset.
+     */
+    readonly eventBackfillServiceName?: string;
     /**
      * The type of allowed ingress that can reach the container.
      * See https://cloud.google.com/run/docs/securing/ingress#settings for more details.

package/dist/configurations/generated.js

@@ -110,6 +110,12 @@ export class GoogleCloudRun {
      * The Docker repository where Cloud Run containers should be uploaded.
      */
     dockerRepository;
+    /**
+     * For `serviceContainer` projects deployed on Cloud Run, the name of the Cloud Run service that receives
+     * events during a backfill targeting a project-scoped trigger. Defaults to the project's name
+     * (`project.name`) when unset.
+     */
+    eventBackfillServiceName;
     /**
      * The type of allowed ingress that can reach the container.
      * See https://cloud.google.com/run/docs/securing/ingress#settings for more details.
@@ -156,6 +162,11 @@ __decorate([
     IsString(),
     __metadata("design:type", String)
 ], GoogleCloudRun.prototype, "dockerRepository", void 0);
+__decorate([
+    AllowMissing(),
+    IsString(),
+    __metadata("design:type", String)
+], GoogleCloudRun.prototype, "eventBackfillServiceName", void 0);
 __decorate([
     AllowMissing(),
     IsIn(['all', 'internal', 'internal-and-cloud-load-balancing']),

package/dist/configurations/schemas/google.yaml

@@ -358,6 +358,16 @@ properties:
           location:
             type: string
             description: The location where Cloud Run services should be deployed.
+          eventBackfillServiceName:
+            type: string
+            description: >-
+              For `serviceContainer` projects deployed on Cloud Run, the name of
+              the Cloud Run service that receives
+
+              events during a backfill targeting a project-scoped trigger.
+              Defaults to the project's name
+
+              (`project.name`) when unset.
           secretEnvironmentVariables:
             type: object
             description: >-

package/dist/functions/event-topic/broker-create-trigger-cloud-run.call.d.ts

@@ -1,3 +1,3 @@
 import type { WorkspaceContext } from '@causa/workspace';
-import type { EventTopicBrokerCreateTriggerForCloudRun } from './broker-create-trigger-cloud-run.js';
+import { type EventTopicBrokerCreateTriggerForCloudRun } from './broker-create-trigger-cloud-run.js';
 export default function call(this: EventTopicBrokerCreateTriggerForCloudRun, context: WorkspaceContext): Promise<string[]>;

package/dist/functions/event-topic/broker-create-trigger-cloud-run.call.js

@@ -1,23 +1,53 @@
 import { CloudRunPubSubTriggerService } from '../../services/cloud-run-pubsub-trigger.js';
+import { CLOUD_RUN_TRIGGER_ID_REGEX, } from './broker-create-trigger-cloud-run.js';
 /**
- * The regular expression used to match Cloud Run trigger IDs, consisting of the service ID and the path to the trigger.
- * [[projects/<projectId>/]locations/<location>/]services/<name>/path-to-trigger
+ * Resolves the Cloud Run service ID and HTTP path for a raw URI trigger string.
  */
-const CLOUD_RUN_TRIGGER_ID_REGEX = /^(?:(?:projects\/(?<projectId>[\w-]+)\/)?locations\/(?<location>[\w-]+)\/)?services\/(?<name>[\w-]+)(?<path>\/.*)$/;
-export default async function call(context) {
-    const match = this.trigger.match(CLOUD_RUN_TRIGGER_ID_REGEX);
+function resolveFromString(context, trigger) {
+    const match = trigger.match(CLOUD_RUN_TRIGGER_ID_REGEX);
     if (!match?.groups) {
-        throw new Error('Oops.');
+        throw new Error(`Invalid Cloud Run trigger '${trigger}'.`);
     }
     const googleConf = context.asConfiguration();
     const projectId = match.groups.projectId ?? googleConf.getOrThrow('google.project');
     const location = match.groups.location ?? googleConf.getOrThrow('google.cloudRun.location');
-    const name = match.groups.name;
-    const path = match.groups.path;
-    if (!name || !path) {
-        throw new Error('Oops.');
+    return {
+        serviceId: `projects/${projectId}/locations/${location}/services/${match.groups.name}`,
+        path: match.groups.path,
+    };
+}
+/**
+ * Resolves the Cloud Run service ID and HTTP path for a project-scoped trigger object.
+ * The project is expected to be a `serviceContainer` deployed on Cloud Run. The service name defaults to the project's
+ * name, and is overridden by `google.cloudRun.eventBackfillServiceName` when set. The trigger path is read from
+ * `serviceContainer.triggers[name].endpoint`, which must be of type `http`. Options are serialized as a URL query
+ * string.
+ *
+ * @param context The {@link WorkspaceContext}.
+ * @param trigger The trigger object.
+ * @returns The resolved service ID and path.
+ */
+function resolveFromObject(context, trigger) {
+    const conf = context.asConfiguration();
+    const projectId = conf.getOrThrow('google.project');
+    const location = conf.getOrThrow('google.cloudRun.location');
+    const serviceName = conf.get('google.cloudRun.eventBackfillServiceName') ??
+        conf.getOrThrow('project.name');
+    const endpoint = conf.get(`serviceContainer.triggers.${trigger.name}.endpoint`);
+    if (!endpoint || endpoint.type !== 'http' || !endpoint.path) {
+        throw new Error(`Trigger '${trigger.name}' does not exist or does not define an HTTP endpoint.`);
     }
-    const serviceId = `projects/${projectId}/locations/${location}/services/${name}`;
+    const query = new URLSearchParams(trigger.options).toString();
+    const path = query ? `${endpoint.path}?${query}` : endpoint.path;
+    return {
+        serviceId: `projects/${projectId}/locations/${location}/services/${serviceName}`,
+        path,
+    };
+}
+export default async function call(context) {
+    const { serviceId, path } = typeof this.trigger === 'string'
+        ? resolveFromString(context, this.trigger)
+        : resolveFromObject(context, this.trigger);
     return await context
         .service(CloudRunPubSubTriggerService)
         .create(this.backfillId, this.topicId, serviceId, path);

package/dist/functions/event-topic/broker-create-trigger-cloud-run.d.ts

@@ -1,9 +1,18 @@
 import { WorkspaceContext } from '@causa/workspace';
 import { EventTopicBrokerCreateTrigger } from '@causa/workspace-core';
+/**
+ * The regular expression used to match Cloud Run trigger IDs, consisting of the service ID and the path to the trigger.
+ * [[projects/<projectId>/]locations/<location>/]services/<name>/path-to-trigger
+ */
+export declare const CLOUD_RUN_TRIGGER_ID_REGEX: RegExp;
 /**
  * Implements {@link EventTopicBrokerCreateTrigger} for Cloud Run endpoints being triggered by Pub/Sub messages.
- * The `id` argument should be a Cloud Run service ID, followed by the path to the trigger, e.g.
- * `[[projects/<projectId>/]locations/<location>/]services/<name>/path-to-trigger`.
+ *
+ * Two forms of trigger are supported:
+ * - A string in the format `[[projects/<projectId>/]locations/<location>/]services/<name>/path-to-trigger`.
+ * - An object `{ name, options }` passed when the function is called on a project-scoped context. In that case the
+ *   project must be a `serviceContainer` deployed on Cloud Run. The trigger's `name` must match an entry in
+ *   `serviceContainer.triggers` whose endpoint is of type `http`. Options are forwarded as URL query parameters.
  */
 export declare class EventTopicBrokerCreateTriggerForCloudRun extends EventTopicBrokerCreateTrigger {
     _call(context: WorkspaceContext): Promise<string[]>;

package/dist/functions/event-topic/broker-create-trigger-cloud-run.js

@@ -4,19 +4,31 @@ import { EventTopicBrokerCreateTrigger, } from '@causa/workspace-core';
  * The regular expression used to match Cloud Run trigger IDs, consisting of the service ID and the path to the trigger.
  * [[projects/<projectId>/]locations/<location>/]services/<name>/path-to-trigger
  */
-const CLOUD_RUN_TRIGGER_ID_REGEX = /^(?:(?:projects\/(?<projectId>[\w-]+)\/)?locations\/(?<location>[\w-]+)\/)?services\/(?<name>[\w-]+)(?<path>\/.*)$/;
+export const CLOUD_RUN_TRIGGER_ID_REGEX = /^(?:(?:projects\/(?<projectId>[\w-]+)\/)?locations\/(?<location>[\w-]+)\/)?services\/(?<name>[\w-]+)(?<path>\/.*)$/;
 /**
  * Implements {@link EventTopicBrokerCreateTrigger} for Cloud Run endpoints being triggered by Pub/Sub messages.
- * The `id` argument should be a Cloud Run service ID, followed by the path to the trigger, e.g.
- * `[[projects/<projectId>/]locations/<location>/]services/<name>/path-to-trigger`.
+ *
+ * Two forms of trigger are supported:
+ * - A string in the format `[[projects/<projectId>/]locations/<location>/]services/<name>/path-to-trigger`.
+ * - An object `{ name, options }` passed when the function is called on a project-scoped context. In that case the
+ *   project must be a `serviceContainer` deployed on Cloud Run. The trigger's `name` must match an entry in
+ *   `serviceContainer.triggers` whose endpoint is of type `http`. Options are forwarded as URL query parameters.
  */
 export class EventTopicBrokerCreateTriggerForCloudRun extends EventTopicBrokerCreateTrigger {
     async _call(context) {
         return await callDeferred(this, context, import.meta.url);
     }
     _supports(context) {
-        return (this.trigger.match(CLOUD_RUN_TRIGGER_ID_REGEX) != null &&
-            context.asConfiguration().get('events.broker') ===
-                'google.pubSub');
+        const isPubSub = context.asConfiguration().get('events.broker') ===
+            'google.pubSub';
+        if (!isPubSub) {
+            return false;
+        }
+        if (typeof this.trigger === 'string') {
+            return CLOUD_RUN_TRIGGER_ID_REGEX.test(this.trigger);
+        }
+        const conf = context.asConfiguration();
+        return (conf.get('project.type') === 'serviceContainer' &&
+            conf.get('serviceContainer.platform') === 'google.cloudRun');
     }
 }

package/dist/functions/event-topic/broker-publish-events-google.call.js

@@ -1,29 +1,45 @@
-import { JsonFilesEventSource, } from '@causa/workspace-core/backfill';
-import { BigQueryEventsSource, PubSubBackfillEventPublisher, } from '../../backfilling/index.js';
-async function createSource(self, context) {
-    if (!self.source) {
-        const googleConf = context.asConfiguration();
-        const projectId = googleConf.getOrThrow('google.project');
-        const rawEventsDatasetId = googleConf.get('google.pubSub.bigQueryStorage.rawEventsDatasetId');
-        if (!rawEventsDatasetId) {
-            throw new Error('Cannot use the default event source because BigQuery storage is not configured.');
+import { FlowControlledPublisher } from '@google-cloud/pubsub/build/src/publisher/flow-publisher.js';
+import { PubSubService } from '../../services/index.js';
+/**
+ * The number of events between each progress log line.
+ */
+const PUBLISH_PROGRESS_LOG_INTERVAL = 10000;
+/**
+ * Options when publishing events in batches to Pub/Sub.
+ */
+const PUBLISH_OPTIONS = {
+    flowControlOptions: {
+        maxOutstandingBytes: 10 * 1024 * 1024,
+        maxOutstandingMessages: 1000,
+    },
+    batching: {
+        maxBytes: 10 * 1024 * 1024,
+        maxMessages: 1000,
+        maxMilliseconds: 1000,
+    },
+};
+export default async function call(context) {
+    const publisher = context
+        .service(PubSubService)
+        .pubSub.topic(this.topicId, PUBLISH_OPTIONS)
+        .flowControlled();
+    context.logger.info('📫 Publishing events.');
+    let numEvents = 0;
+    for await (const event of this.source()) {
+        numEvents += 1;
+        const wait = publisher.publish({
+            data: event.data,
+            attributes: event.attributes,
+            orderingKey: event.key,
+        });
+        if (wait) {
+            context.logger.debug('Waiting for the publisher to catch up before resuming publishing.');
+            await wait;
+        }
+        if (numEvents % PUBLISH_PROGRESS_LOG_INTERVAL === 0) {
+            context.logger.debug(`Published ${numEvents} events.`);
         }
-        const tableName = self.eventTopic.replace(/[-\.]/g, '_');
-        const tableId = `${projectId}.${rawEventsDatasetId}.${tableName}`;
-        return new BigQueryEventsSource(context, tableId);
-    }
-    const bqSource = await BigQueryEventsSource.fromSourceAndFilter(context, self.source, self.filter);
-    if (bqSource) {
-        return bqSource;
-    }
-    const jsonFilesSource = await JsonFilesEventSource.fromSourceAndFilter(context, self.source, self.filter);
-    if (jsonFilesSource) {
-        return jsonFilesSource;
     }
-    throw new Error(`The event source '${self.source}' is not supported.`);
-}
-export default async function call(context) {
-    const source = await createSource(this, context);
-    const publisher = new PubSubBackfillEventPublisher(context, this.topicId);
-    await publisher.publishFromSource(source);
+    await publisher.all();
+    context.logger.info(`📫 Finished publishing ${numEvents} events.`);
 }

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

@@ -0,0 +1,4 @@
+import type { WorkspaceContext } from '@causa/workspace';
+import type { BackfillEvent } from '@causa/workspace-core';
+import { type EventTopicCreateBackfillSourceForBigQuery } from './create-backfill-source-bigquery.js';
+export default function call(this: EventTopicCreateBackfillSourceForBigQuery, context: WorkspaceContext): Promise<AsyncIterable<BackfillEvent>>;

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

@@ -0,0 +1,48 @@
+import { BigQueryService } from '../../services/index.js';
+import { BIGQUERY_SOURCE_REGEX, } from './create-backfill-source-bigquery.js';
+/**
+ * Resolves the full BigQuery table ID from the function arguments and configuration.
+ *
+ * @param self The function instance.
+ * @param context The {@link WorkspaceContext}.
+ * @returns The full BigQuery table ID, in the format `projectId.datasetId.tableId`.
+ */
+function resolveTableId(self, context) {
+    if (self.source) {
+        const match = self.source.match(BIGQUERY_SOURCE_REGEX);
+        if (!match?.groups?.tableId) {
+            throw new Error(`The source '${self.source}' is not a valid BigQuery source.`);
+        }
+        return match.groups.tableId;
+    }
+    const googleConf = context.asConfiguration();
+    const projectId = googleConf.getOrThrow('google.project');
+    const rawEventsDatasetId = googleConf.getOrThrow('google.pubSub.bigQueryStorage.rawEventsDatasetId');
+    const tableName = self.eventTopic.replace(/[-\.]/g, '_');
+    return `${projectId}.${rawEventsDatasetId}.${tableName}`;
+}
+export default async function call(context) {
+    const tableId = resolveTableId(this, context);
+    let query = `
+    SELECT
+      data,
+      attributes,
+    FROM
+      \`${tableId}\``;
+    if (this.filter) {
+        query += `
+    WHERE
+      (${this.filter})`;
+    }
+    context.logger.debug(`Creating BigQuery job from query '${query}'.`);
+    const bigQuery = context.service(BigQueryService).bigQuery;
+    const [job] = await bigQuery.createQueryJob(query);
+    return (async function* () {
+        for await (const row of job.getQueryResultsStream()) {
+            yield {
+                data: Buffer.from(row.data),
+                attributes: JSON.parse(row.attributes),
+            };
+        }
+    })();
+}

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

@@ -0,0 +1,20 @@
+import { WorkspaceContext } from '@causa/workspace';
+import { type BackfillEvent, EventTopicCreateBackfillSource } from '@causa/workspace-core';
+/**
+ * The regular expression used to parse a `bq://<tableId>` source string.
+ */
+export declare const BIGQUERY_SOURCE_REGEX: RegExp;
+/**
+ * Implements {@link EventTopicCreateBackfillSource} for BigQuery tables.
+ *
+ * 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.
+ *
+ * The returned async iterable pages through the query results and yields each row as a {@link BackfillEvent}.
+ */
+export declare class EventTopicCreateBackfillSourceForBigQuery extends EventTopicCreateBackfillSource {
+    _call(context: WorkspaceContext): Promise<AsyncIterable<BackfillEvent>>;
+    _supports(context: WorkspaceContext): boolean;
+}

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

@@ -0,0 +1,32 @@
+import { callDeferred, WorkspaceContext } from '@causa/workspace';
+import { EventTopicCreateBackfillSource, } from '@causa/workspace-core';
+/**
+ * The regular expression used to parse a `bq://<tableId>` source string.
+ */
+export const BIGQUERY_SOURCE_REGEX = /^bq:\/\/(?<tableId>.+)$/;
+/**
+ * Implements {@link EventTopicCreateBackfillSource} for BigQuery tables.
+ *
+ * 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.
+ *
+ * The returned async iterable pages through the query results and yields each row as a {@link BackfillEvent}.
+ */
+export class EventTopicCreateBackfillSourceForBigQuery extends EventTopicCreateBackfillSource {
+    async _call(context) {
+        return await callDeferred(this, context, import.meta.url);
+    }
+    _supports(context) {
+        if (this.source?.match(BIGQUERY_SOURCE_REGEX)) {
+            return true;
+        }
+        if (this.source) {
+            return false;
+        }
+        const conf = context.asConfiguration();
+        return (conf.get('events.broker') === 'google.pubSub' &&
+            !!conf.get('google.pubSub.bigQueryStorage.rawEventsDatasetId'));
+    }
+}

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

@@ -6,3 +6,5 @@ export { EventTopicBrokerDeleteTriggerResourceForPubSubSubscription } from './br
 export { EventTopicBrokerDeleteTriggerResourceForServiceAccount } from './broker-delete-trigger-resource-service-account.js';
 export { EventTopicBrokerGetTopicIdForPubSub } from './broker-get-topic-id-pubsub.js';
 export { EventTopicBrokerPublishEventsForGoogle } from './broker-publish-events-google.js';
+export { EventTopicCreateBackfillSourceForBigQuery } from './create-backfill-source-bigquery.js';
+export { EventTopicQueryEventsForBigQuery } from './query-events-bigquery.js';

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

@@ -6,3 +6,5 @@ export { EventTopicBrokerDeleteTriggerResourceForPubSubSubscription } from './br
 export { EventTopicBrokerDeleteTriggerResourceForServiceAccount } from './broker-delete-trigger-resource-service-account.js';
 export { EventTopicBrokerGetTopicIdForPubSub } from './broker-get-topic-id-pubsub.js';
 export { EventTopicBrokerPublishEventsForGoogle } from './broker-publish-events-google.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.d.ts

@@ -0,0 +1,4 @@
+import type { WorkspaceContext } from '@causa/workspace';
+import type { QueriedEvent } from '@causa/workspace-core';
+import type { EventTopicQueryEventsForBigQuery } from './query-events-bigquery.js';
+export default function call(this: EventTopicQueryEventsForBigQuery, context: WorkspaceContext): Promise<QueriedEvent[]>;

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

@@ -0,0 +1,41 @@
+import { BigQueryService } from '../../services/index.js';
+/**
+ * The default duration applied to `from` when it is not set, in milliseconds.
+ */
+const DEFAULT_FROM_OFFSET = 60 * 60 * 1000;
+/**
+ * The default value for `limit` when it is not set.
+ */
+const DEFAULT_LIMIT = 1000;
+export default async function call(context) {
+    const from = this.from ?? new Date(Date.now() - DEFAULT_FROM_OFFSET);
+    const limit = this.limit ?? DEFAULT_LIMIT;
+    const googleConf = context.asConfiguration();
+    const projectId = googleConf.getOrThrow('google.project');
+    const rawEventsDatasetId = googleConf.getOrThrow('google.pubSub.bigQueryStorage.rawEventsDatasetId');
+    const tableName = this.topic.replace(/[-\.]/g, '_');
+    const tableId = `${projectId}.${rawEventsDatasetId}.${tableName}`;
+    const conditions = [`publish_time >= @from`];
+    const params = { from: from.toISOString() };
+    if (this.to) {
+        conditions.push(`publish_time < @to`);
+        params.to = this.to.toISOString();
+    }
+    if (this.filter) {
+        conditions.push(`(${this.filter})`);
+    }
+    const query = `
+    SELECT publish_time, data, attributes
+    FROM \`${tableId}\`
+    WHERE ${conditions.join(' AND ')}
+    ORDER BY publish_time ASC
+    LIMIT ${limit}`;
+    context.logger.debug(`Querying BigQuery for events:\n${query}`);
+    const bigQuery = context.service(BigQueryService).bigQuery;
+    const [rows] = await bigQuery.query({ query, params });
+    return rows.map((row) => ({
+        timestamp: new Date(row.publish_time.value),
+        attributes: row.attributes ? JSON.parse(row.attributes) : {},
+        data: JSON.parse(row.data.toString('utf8')),
+    }));
+}

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

@@ -0,0 +1,10 @@
+import { WorkspaceContext } from '@causa/workspace';
+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`.
+ */
+export declare class EventTopicQueryEventsForBigQuery extends EventTopicQueryEvents {
+    _call(context: WorkspaceContext): Promise<QueriedEvent[]>;
+    _supports(context: WorkspaceContext): boolean;
+}

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

@@ -0,0 +1,17 @@
+import { callDeferred, WorkspaceContext } from '@causa/workspace';
+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`.
+ */
+export class EventTopicQueryEventsForBigQuery extends EventTopicQueryEvents {
+    async _call(context) {
+        return await callDeferred(this, context, import.meta.url);
+    }
+    _supports(context) {
+        const conf = context.asConfiguration();
+        return (conf.get('events.broker') === 'google.pubSub' &&
+            conf.get('events.format') === 'json' &&
+            !!conf.get('google.pubSub.bigQueryStorage.rawEventsDatasetId'));
+    }
+}

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

@@ -1 +1,2 @@
+export { DatabaseQueryRecordsForFirestore } from './query-records.js';
 export { GoogleFirestoreMergeRules } from './merge-rules.js';

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

@@ -1 +1,2 @@
+export { DatabaseQueryRecordsForFirestore } from './query-records.js';
 export { GoogleFirestoreMergeRules } from './merge-rules.js';

package/dist/functions/google-firestore/query-records.call.d.ts

@@ -0,0 +1,3 @@
+import type { WorkspaceContext } from '@causa/workspace';
+import type { DatabaseQueryRecordsForFirestore } from './query-records.js';
+export default function call(this: DatabaseQueryRecordsForFirestore, context: WorkspaceContext): Promise<any[]>;

package/dist/functions/google-firestore/query-records.call.js

@@ -0,0 +1,50 @@
+import { deleteApp, initializeApp } from 'firebase-admin/app';
+import { DocumentReference, GeoPoint, getFirestore, Timestamp, } from 'firebase-admin/firestore';
+import { randomUUID } from 'node:crypto';
+export default async function call(context) {
+    if (!this.query) {
+        throw new Error(`The 'query' input is required for the 'google.firestore' engine.`);
+    }
+    const googleConf = context.asConfiguration();
+    const projectId = googleConf.getOrThrow('google.project');
+    const database = this.database ?? '(default)';
+    context.logger.debug(`🗃️ Fetching Firestore document '${this.query}' from database '${database}' in project '${projectId}'.`);
+    const app = initializeApp({ projectId }, randomUUID());
+    try {
+        const firestore = getFirestore(app, database);
+        const snapshot = await firestore.doc(this.query).get();
+        return snapshot.exists ? [toJson(snapshot.data())] : [];
+    }
+    finally {
+        await deleteApp(app);
+    }
+}
+/**
+ * Recursively converts Firestore-specific types to JSON-friendly equivalents:
+ * - {@link Timestamp} → {@link Date}
+ * - {@link GeoPoint} → `{ latitude, longitude }`
+ * - {@link DocumentReference} → its `path`
+ *
+ * Other values (including `Buffer`) are returned as-is.
+ */
+function toJson(value) {
+    if (value === null || typeof value !== 'object') {
+        return value;
+    }
+    if (value instanceof Timestamp) {
+        return value.toDate();
+    }
+    if (value instanceof GeoPoint) {
+        return { latitude: value.latitude, longitude: value.longitude };
+    }
+    if (value instanceof DocumentReference) {
+        return value.path;
+    }
+    if (Buffer.isBuffer(value)) {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        return value.map(toJson);
+    }
+    return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, toJson(v)]));
+}

package/dist/functions/google-firestore/query-records.d.ts

@@ -0,0 +1,18 @@
+import { WorkspaceContext } from '@causa/workspace';
+import { DatabaseQueryRecords } from '@causa/workspace-core';
+/**
+ * The engine identifier handled by this implementation.
+ */
+export declare const FIRESTORE_ENGINE = "google.firestore";
+/**
+ * Implements {@link DatabaseQueryRecords} for Firestore.
+ *
+ * The `database` input is optional and defaults to the default Firestore database. The `query` input is the path to a
+ * single document (e.g. `users/abc`).
+ *
+ * Returns an array containing a single document's data, or an empty array if the document does not exist.
+ */
+export declare class DatabaseQueryRecordsForFirestore extends DatabaseQueryRecords {
+    _call(context: WorkspaceContext): Promise<any[]>;
+    _supports(): boolean;
+}

package/dist/functions/google-firestore/query-records.js

@@ -0,0 +1,22 @@
+import { callDeferred, WorkspaceContext } from '@causa/workspace';
+import { DatabaseQueryRecords } from '@causa/workspace-core';
+/**
+ * The engine identifier handled by this implementation.
+ */
+export const FIRESTORE_ENGINE = 'google.firestore';
+/**
+ * Implements {@link DatabaseQueryRecords} for Firestore.
+ *
+ * The `database` input is optional and defaults to the default Firestore database. The `query` input is the path to a
+ * single document (e.g. `users/abc`).
+ *
+ * Returns an array containing a single document's data, or an empty array if the document does not exist.
+ */
+export class DatabaseQueryRecordsForFirestore extends DatabaseQueryRecords {
+    async _call(context) {
+        return await callDeferred(this, context, import.meta.url);
+    }
+    _supports() {
+        return this.engine === FIRESTORE_ENGINE;
+    }
+}

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

@@ -1,2 +1,3 @@
 export { GoogleSpannerListDatabases } from './list-databases.js';
+export { DatabaseQueryRecordsForSpanner } from './query-records.js';
 export { GoogleSpannerWriteDatabases } from './write-databases.js';

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

@@ -1,2 +1,3 @@
 export { GoogleSpannerListDatabases } from './list-databases.js';
+export { DatabaseQueryRecordsForSpanner } from './query-records.js';
 export { GoogleSpannerWriteDatabases } from './write-databases.js';

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

@@ -0,0 +1,3 @@
+import type { WorkspaceContext } from '@causa/workspace';
+import { type DatabaseQueryRecordsForSpanner } from './query-records.js';
+export default function call(this: DatabaseQueryRecordsForSpanner, context: WorkspaceContext): Promise<any[]>;