@tmlmobilidade/go-interfaces-labdb 20260811.1505.45 → 20260828.1636.54

package/dist/databases/operation.d.ts

@@ -1,8 +1,28 @@
 import { ClickHouseInterfaceTemplate } from '../interface.template.js';
 import { ClickHouseClient } from '@tmlmobilidade/go-clients-clickhouse';
+import { HashedShape, type HashedTrip, type RideAnalysisAtLeastOneVehicleEventOnFirstStop, type RideAnalysisAtLeastOneVehicleEventOnLastStop, type RideAnalysisExpectedApexValidationInterval, type RideAnalysisExpectedDriverIdQty, type RideAnalysisExpectedStartTime, type RideAnalysisExpectedVehicleEventDelay, type RideAnalysisExpectedVehicleEventInterval, type RideAnalysisExpectedVehicleEventQty, type RideAnalysisExpectedVehicleIdQty, type RideAnalysisMatchingApexLocations, type RideAnalysisMatchingVehicleIds, type RideAnalysisSimpleOneApexValidation, type RideAnalysisSimpleOneVehicleEventOrApexValidation, type RideAnalysisSimpleThreeVehicleEvents, type RideAnalysisTransactionSequentiality } from '@tmlmobilidade/go-types-operation';
+import { type Ride } from '@tmlmobilidade/go-types-operation';
 import { type SimplifiedVehicleEvent } from '@tmlmobilidade/go-types-vehicle-events';
 export declare class OperationDatabase {
-    readonly vehicleEvents: ClickHouseInterfaceTemplate<SimplifiedVehicleEvent>;
+    readonly hashedShapes: ClickHouseInterfaceTemplate<HashedShape>;
+    readonly hashedTrips: ClickHouseInterfaceTemplate<HashedTrip>;
+    readonly rideAnalysisAtLeastOneVehicleEventOnFirstStop: ClickHouseInterfaceTemplate<RideAnalysisAtLeastOneVehicleEventOnFirstStop>;
+    readonly rideAnalysisAtLeastOneVehicleEventOnLastStop: ClickHouseInterfaceTemplate<RideAnalysisAtLeastOneVehicleEventOnLastStop>;
+    readonly rideAnalysisExpectedApexValidationInterval: ClickHouseInterfaceTemplate<RideAnalysisExpectedApexValidationInterval>;
+    readonly rideAnalysisExpectedDriverIdQty: ClickHouseInterfaceTemplate<RideAnalysisExpectedDriverIdQty>;
+    readonly rideAnalysisExpectedStartTime: ClickHouseInterfaceTemplate<RideAnalysisExpectedStartTime>;
+    readonly rideAnalysisExpectedVehicleEventDelay: ClickHouseInterfaceTemplate<RideAnalysisExpectedVehicleEventDelay>;
+    readonly rideAnalysisExpectedVehicleEventInterval: ClickHouseInterfaceTemplate<RideAnalysisExpectedVehicleEventInterval>;
+    readonly rideAnalysisExpectedVehicleEventQty: ClickHouseInterfaceTemplate<RideAnalysisExpectedVehicleEventQty>;
+    readonly rideAnalysisExpectedVehicleIdQty: ClickHouseInterfaceTemplate<RideAnalysisExpectedVehicleIdQty>;
+    readonly rideAnalysisMatchingApexLocations: ClickHouseInterfaceTemplate<RideAnalysisMatchingApexLocations>;
+    readonly rideAnalysisMatchingVehicleIds: ClickHouseInterfaceTemplate<RideAnalysisMatchingVehicleIds>;
+    readonly rideAnalysisSimpleOneApexValidation: ClickHouseInterfaceTemplate<RideAnalysisSimpleOneApexValidation>;
+    readonly rideAnalysisSimpleOneVehicleEventOrApexValidation: ClickHouseInterfaceTemplate<RideAnalysisSimpleOneVehicleEventOrApexValidation>;
+    readonly rideAnalysisSimpleThreeVehicleEvents: ClickHouseInterfaceTemplate<RideAnalysisSimpleThreeVehicleEvents>;
+    readonly rideAnalysisTransactionSequentiality: ClickHouseInterfaceTemplate<RideAnalysisTransactionSequentiality>;
+    readonly rides: ClickHouseInterfaceTemplate<Ride>;
+    readonly simplifiedVehicleEvents: ClickHouseInterfaceTemplate<SimplifiedVehicleEvent>;
     private readonly databaseName;
     constructor(instance: ClickHouseClient);
     init(): Promise<void>;

package/dist/databases/operation.js

@@ -1,19 +1,145 @@
 /* * */
 import { ClickHouseInterfaceTemplate } from '../interface.template.js';
-import { simplifiedVehicleEventTableSchema } from '../schemas/operation.js';
+import { hashedShapeTableSchema, hashedTripTableSchema, rideAnalysisAtLeastOneVehicleEventOnFirstStopTableSchema, rideAnalysisAtLeastOneVehicleEventOnLastStopTableSchema, rideAnalysisExpectedApexValidationIntervalTableSchema, rideAnalysisExpectedDriverIdQtyTableSchema, rideAnalysisExpectedStartTimeTableSchema, rideAnalysisExpectedVehicleEventDelayTableSchema, rideAnalysisExpectedVehicleEventIntervalTableSchema, rideAnalysisExpectedVehicleEventQtyTableSchema, rideAnalysisExpectedVehicleIdQtyTableSchema, rideAnalysisMatchingApexLocationsTableSchema, rideAnalysisMatchingVehicleIdsTableSchema, rideAnalysisSimpleOneApexValidationTableSchema, rideAnalysisSimpleOneVehicleEventOrApexValidationTableSchema, rideAnalysisSimpleThreeVehicleEventsTableSchema, rideAnalysisTransactionSequentialityTableSchema, ridesTableSchema, simplifiedVehicleEventTableSchema } from '../schemas/operation.js';
 /* * */
 export class OperationDatabase {
     //
-    vehicleEvents;
+    hashedShapes;
+    hashedTrips;
+    rideAnalysisAtLeastOneVehicleEventOnFirstStop;
+    rideAnalysisAtLeastOneVehicleEventOnLastStop;
+    rideAnalysisExpectedApexValidationInterval;
+    rideAnalysisExpectedDriverIdQty;
+    rideAnalysisExpectedStartTime;
+    rideAnalysisExpectedVehicleEventDelay;
+    rideAnalysisExpectedVehicleEventInterval;
+    rideAnalysisExpectedVehicleEventQty;
+    rideAnalysisExpectedVehicleIdQty;
+    rideAnalysisMatchingApexLocations;
+    rideAnalysisMatchingVehicleIds;
+    rideAnalysisSimpleOneApexValidation;
+    rideAnalysisSimpleOneVehicleEventOrApexValidation;
+    rideAnalysisSimpleThreeVehicleEvents;
+    rideAnalysisTransactionSequentiality;
+    rides;
+    simplifiedVehicleEvents;
     databaseName = 'operation';
     constructor(instance) {
-        this.vehicleEvents = new ClickHouseInterfaceTemplate(instance, this.databaseName, 'simplified_vehicle_events', simplifiedVehicleEventTableSchema, {
+        this.hashedShapes = new ClickHouseInterfaceTemplate(instance, this.databaseName, 'hashed_shapes', hashedShapeTableSchema, {
+            engine: 'ReplacingMergeTree(updated_at)',
+            orderBy: ['_id', 'shape_id'],
+            partitionBy: undefined,
+        });
+        this.hashedTrips = new ClickHouseInterfaceTemplate(instance, this.databaseName, 'hashed_trips', hashedTripTableSchema, {
+            engine: 'ReplacingMergeTree(updated_at)',
+            orderBy: ['_id', 'stop_sequence'],
+            partitionBy: undefined,
+        });
+        this.rideAnalysisAtLeastOneVehicleEventOnFirstStop = new ClickHouseInterfaceTemplate(instance, this.databaseName, 'ride_analysis_at_least_one_vehicle_event_on_first_stop', rideAnalysisAtLeastOneVehicleEventOnFirstStopTableSchema, {
+            engine: 'ReplacingMergeTree(updated_at)',
+            orderBy: ['ride_id'],
+            partitionBy: 'intDiv(operational_date, 100)',
+        });
+        this.rideAnalysisAtLeastOneVehicleEventOnLastStop = new ClickHouseInterfaceTemplate(instance, this.databaseName, 'ride_analysis_at_least_one_vehicle_event_on_last_stop', rideAnalysisAtLeastOneVehicleEventOnLastStopTableSchema, {
+            engine: 'ReplacingMergeTree(updated_at)',
+            orderBy: ['ride_id'],
+            partitionBy: 'intDiv(operational_date, 100)',
+        });
+        this.rideAnalysisExpectedApexValidationInterval = new ClickHouseInterfaceTemplate(instance, this.databaseName, 'ride_analysis_expected_apex_validation_interval', rideAnalysisExpectedApexValidationIntervalTableSchema, {
+            engine: 'ReplacingMergeTree(updated_at)',
+            orderBy: ['ride_id'],
+            partitionBy: 'intDiv(operational_date, 100)',
+        });
+        this.rideAnalysisExpectedDriverIdQty = new ClickHouseInterfaceTemplate(instance, this.databaseName, 'ride_analysis_expected_driver_id_qty', rideAnalysisExpectedDriverIdQtyTableSchema, {
+            engine: 'ReplacingMergeTree(updated_at)',
+            orderBy: ['ride_id'],
+            partitionBy: 'intDiv(operational_date, 100)',
+        });
+        this.rideAnalysisExpectedStartTime = new ClickHouseInterfaceTemplate(instance, this.databaseName, 'ride_analysis_expected_start_time', rideAnalysisExpectedStartTimeTableSchema, {
+            engine: 'ReplacingMergeTree(updated_at)',
+            orderBy: ['ride_id'],
+            partitionBy: 'intDiv(operational_date, 100)',
+        });
+        this.rideAnalysisExpectedVehicleEventDelay = new ClickHouseInterfaceTemplate(instance, this.databaseName, 'ride_analysis_expected_vehicle_event_delay', rideAnalysisExpectedVehicleEventDelayTableSchema, {
+            engine: 'ReplacingMergeTree(updated_at)',
+            orderBy: ['ride_id'],
+            partitionBy: 'intDiv(operational_date, 100)',
+        });
+        this.rideAnalysisExpectedVehicleEventInterval = new ClickHouseInterfaceTemplate(instance, this.databaseName, 'ride_analysis_expected_vehicle_event_interval', rideAnalysisExpectedVehicleEventIntervalTableSchema, {
+            engine: 'ReplacingMergeTree(updated_at)',
+            orderBy: ['ride_id'],
+            partitionBy: 'intDiv(operational_date, 100)',
+        });
+        this.rideAnalysisExpectedVehicleEventQty = new ClickHouseInterfaceTemplate(instance, this.databaseName, 'ride_analysis_expected_vehicle_event_qty', rideAnalysisExpectedVehicleEventQtyTableSchema, {
+            engine: 'ReplacingMergeTree(updated_at)',
+            orderBy: ['ride_id'],
+            partitionBy: 'intDiv(operational_date, 100)',
+        });
+        this.rideAnalysisExpectedVehicleIdQty = new ClickHouseInterfaceTemplate(instance, this.databaseName, 'ride_analysis_expected_vehicle_id_qty', rideAnalysisExpectedVehicleIdQtyTableSchema, {
+            engine: 'ReplacingMergeTree(updated_at)',
+            orderBy: ['ride_id'],
+            partitionBy: 'intDiv(operational_date, 100)',
+        });
+        this.rideAnalysisMatchingApexLocations = new ClickHouseInterfaceTemplate(instance, this.databaseName, 'ride_analysis_matching_apex_locations', rideAnalysisMatchingApexLocationsTableSchema, {
+            engine: 'ReplacingMergeTree(updated_at)',
+            orderBy: ['ride_id'],
+            partitionBy: 'intDiv(operational_date, 100)',
+        });
+        this.rideAnalysisMatchingVehicleIds = new ClickHouseInterfaceTemplate(instance, this.databaseName, 'ride_analysis_matching_vehicle_ids', rideAnalysisMatchingVehicleIdsTableSchema, {
+            engine: 'ReplacingMergeTree(updated_at)',
+            orderBy: ['ride_id'],
+            partitionBy: 'intDiv(operational_date, 100)',
+        });
+        this.rideAnalysisSimpleOneApexValidation = new ClickHouseInterfaceTemplate(instance, this.databaseName, 'ride_analysis_simple_one_apex_validation', rideAnalysisSimpleOneApexValidationTableSchema, {
+            engine: 'ReplacingMergeTree(updated_at)',
+            orderBy: ['ride_id'],
+            partitionBy: 'intDiv(operational_date, 100)',
+        });
+        this.rideAnalysisSimpleOneVehicleEventOrApexValidation = new ClickHouseInterfaceTemplate(instance, this.databaseName, 'ride_analysis_simple_one_vehicle_event_or_apex_validation', rideAnalysisSimpleOneVehicleEventOrApexValidationTableSchema, {
+            engine: 'ReplacingMergeTree(updated_at)',
+            orderBy: ['ride_id'],
+            partitionBy: 'intDiv(operational_date, 100)',
+        });
+        this.rideAnalysisSimpleThreeVehicleEvents = new ClickHouseInterfaceTemplate(instance, this.databaseName, 'ride_analysis_simple_three_vehicle_events', rideAnalysisSimpleThreeVehicleEventsTableSchema, {
+            engine: 'ReplacingMergeTree(updated_at)',
+            orderBy: ['ride_id'],
+            partitionBy: 'intDiv(operational_date, 100)',
+        });
+        this.rideAnalysisTransactionSequentiality = new ClickHouseInterfaceTemplate(instance, this.databaseName, 'ride_analysis_transaction_sequentiality', rideAnalysisTransactionSequentialityTableSchema, {
+            engine: 'ReplacingMergeTree(updated_at)',
+            orderBy: ['ride_id'],
+            partitionBy: 'intDiv(operational_date, 100)',
+        });
+        this.rides = new ClickHouseInterfaceTemplate(instance, this.databaseName, 'rides', ridesTableSchema, {
+            engine: 'ReplacingMergeTree(updated_at)',
+            orderBy: ['agency_id', 'operational_date', 'route_short_name', 'shape_id', 'start_time_scheduled', '_id'],
+            partitionBy: 'intDiv(operational_date, 100)',
+        });
+        this.simplifiedVehicleEvents = new ClickHouseInterfaceTemplate(instance, this.databaseName, 'simplified_vehicle_events', simplifiedVehicleEventTableSchema, {
             engine: 'ReplacingMergeTree(created_at)',
             orderBy: ['agency_id', 'operational_date', 'vehicle_id', 'created_at', '_id'],
             partitionBy: 'intDiv(operational_date, 100)',
         });
     }
     async init() {
-        await this.vehicleEvents.init();
+        await this.hashedShapes.init();
+        await this.hashedTrips.init();
+        await this.rideAnalysisAtLeastOneVehicleEventOnFirstStop.init();
+        await this.rideAnalysisAtLeastOneVehicleEventOnLastStop.init();
+        await this.rideAnalysisExpectedApexValidationInterval.init();
+        await this.rideAnalysisExpectedDriverIdQty.init();
+        await this.rideAnalysisExpectedStartTime.init();
+        await this.rideAnalysisExpectedVehicleEventDelay.init();
+        await this.rideAnalysisExpectedVehicleEventInterval.init();
+        await this.rideAnalysisExpectedVehicleEventQty.init();
+        await this.rideAnalysisExpectedVehicleIdQty.init();
+        await this.rideAnalysisMatchingApexLocations.init();
+        await this.rideAnalysisMatchingVehicleIds.init();
+        await this.rideAnalysisSimpleOneApexValidation.init();
+        await this.rideAnalysisSimpleOneVehicleEventOrApexValidation.init();
+        await this.rideAnalysisSimpleThreeVehicleEvents.init();
+        await this.rideAnalysisTransactionSequentiality.init();
+        await this.rides.init();
+        await this.simplifiedVehicleEvents.init();
     }
 }

package/dist/interface.d.ts

@@ -1,4 +1,4 @@
-import { ClickHouseClient, queryFromFile, queryFromString } from '@tmlmobilidade/go-clients-clickhouse';
+import { ClickHouseClient, queryEachStatementFromFile, queryFromFile, queryFromString } from '@tmlmobilidade/go-clients-clickhouse';
 import { OperationDatabase } from './databases/operation.js';
 import { PerformanceDatabase } from './databases/performance.js';
 import { SimplifiedApexDatabase } from './databases/simplified-apex.js';
@@ -14,6 +14,14 @@ declare class LabDbClass {
      * Concurrent callers share the same initialization promise so schema setup runs once.
      */
     static getInstance(): Promise<LabDbClass>;
+    /**
+     * It should be used for statements that do not have any output,
+     * when the format clause is not applicable, or when you are not interested in the response at all.
+     * The response stream is destroyed immediately as we do not expect useful information there.
+     *
+     * Examples of such statements are DDLs or custom inserts.
+     */
+    command(...args: Parameters<ClickHouseClient['command']>): Promise<import("@clickhouse/client").CommandResult>;
     /**
      * Returns the ClickHouse client.
      * @returns The ClickHouse client.
@@ -22,6 +30,35 @@ declare class LabDbClass {
      */
     getClient(): Promise<ClickHouseClient>;
     private init;
+    /**
+     * The primary method for data insertion. It is recommended to avoid arrays in case of large inserts
+     * to reduce application memory consumption and consider streaming for most of such use cases.
+     * As the insert operation does not provide any output, the response stream is immediately destroyed.
+     */
+    insert(...args: Parameters<ClickHouseClient['insert']>): Promise<import("@clickhouse/client").InsertResult>;
+    /**
+     * Used for most statements that can have a response, such as `SELECT`.
+     *
+     * The `FORMAT` clause should be specified separately via {@link QueryParams.format} (default is `JSON`);
+     * this method will always append `FORMAT <format>` to the end of {@link QueryParams.query}.
+     * If the query already contains a `FORMAT` clause, ClickHouse will return a syntax error due to a duplicate `FORMAT`.
+     * This is intended behavior.
+     *
+     * Use {@link labDb.insert} for data insertion, {@link labDb.command} for DDLs.
+     */
+    query(...args: Parameters<ClickHouseClient['query']>): Promise<import("@clickhouse/client").ResultSet<unknown>>;
+    /**
+     * Executes a query from a .sql file with optional parameter substitutions.
+     * @param filePath Absolute or relative path to the .sql file.
+     * @param params Optional key-value substitutions applied to the query (replaces {key} placeholders).
+     * @returns Query result rows typed as `T`.
+     * @example
+     * const users = await labDb.queryEachStatementFromFile<User>('get_users.sql', {
+     *   start_date: '2024-01-01',
+     *   end_date: '2024-12-31',
+     * });
+    */
+    queryEachStatementFromFile<T>(filePath: string, params?: Record<string, number | string | string[]>): ReturnType<typeof queryEachStatementFromFile<T>>;
     /**
      * Executes a query from a .sql file with optional parameter substitutions.
      * @param filePath Absolute or relative path to the .sql file.
@@ -48,7 +85,7 @@ declare class LabDbClass {
      *   { start_date: '2024-01-01', end_date: '2024-12-31' }
      * );
     */
-    queryFromString<T>(query: string, params?: Record<string, number | string>): ReturnType<typeof queryFromString<T>>;
+    queryFromString<T>(query: string, params?: Record<string, number | string | string[]>): ReturnType<typeof queryFromString<T>>;
 }
 export declare const labDb: LabDbClass;
 export {};

package/dist/interface.js

@@ -1,5 +1,5 @@
 /* * */
-import { ClickHouseDatabaseClient, queryFromFile, queryFromString } from '@tmlmobilidade/go-clients-clickhouse';
+import { ClickHouseDatabaseClient, queryEachStatementFromFile, queryFromFile, queryFromString } from '@tmlmobilidade/go-clients-clickhouse';
 import { asyncSingletonProxy } from '@tmlmobilidade/utils';
 import { OperationDatabase } from './databases/operation.js';
 import { PerformanceDatabase } from './databases/performance.js';
@@ -34,6 +34,16 @@ class LabDbClass {
         }
         return await LabDbClass._instance;
     }
+    /**
+     * It should be used for statements that do not have any output,
+     * when the format clause is not applicable, or when you are not interested in the response at all.
+     * The response stream is destroyed immediately as we do not expect useful information there.
+     *
+     * Examples of such statements are DDLs or custom inserts.
+     */
+    async command(...args) {
+        return await this.clickhouseClient.command(...args);
+    }
     /**
      * Returns the ClickHouse client.
      * @returns The ClickHouse client.
@@ -51,6 +61,41 @@ class LabDbClass {
             this.simplifiedApex.init(),
         ]);
     }
+    /**
+     * The primary method for data insertion. It is recommended to avoid arrays in case of large inserts
+     * to reduce application memory consumption and consider streaming for most of such use cases.
+     * As the insert operation does not provide any output, the response stream is immediately destroyed.
+     */
+    async insert(...args) {
+        return await this.clickhouseClient.insert(...args);
+    }
+    /**
+     * Used for most statements that can have a response, such as `SELECT`.
+     *
+     * The `FORMAT` clause should be specified separately via {@link QueryParams.format} (default is `JSON`);
+     * this method will always append `FORMAT <format>` to the end of {@link QueryParams.query}.
+     * If the query already contains a `FORMAT` clause, ClickHouse will return a syntax error due to a duplicate `FORMAT`.
+     * This is intended behavior.
+     *
+     * Use {@link labDb.insert} for data insertion, {@link labDb.command} for DDLs.
+     */
+    async query(...args) {
+        return await this.clickhouseClient.query(...args);
+    }
+    /**
+     * Executes a query from a .sql file with optional parameter substitutions.
+     * @param filePath Absolute or relative path to the .sql file.
+     * @param params Optional key-value substitutions applied to the query (replaces {key} placeholders).
+     * @returns Query result rows typed as `T`.
+     * @example
+     * const users = await labDb.queryEachStatementFromFile<User>('get_users.sql', {
+     *   start_date: '2024-01-01',
+     *   end_date: '2024-12-31',
+     * });
+    */
+    async queryEachStatementFromFile(filePath, params) {
+        return await queryEachStatementFromFile(this.clickhouseClient, filePath, params);
+    }
     /**
      * Executes a query from a .sql file with optional parameter substitutions.
      * @param filePath Absolute or relative path to the .sql file.

package/dist/interface.template.d.ts

@@ -37,12 +37,12 @@ export declare class ClickHouseInterfaceTemplate<T extends object> {
     delete(where: string, params?: Record<string, number | string | string[]>): Promise<void>;
     /**
      * Executes a DISTINCT query on the ClickHouse table using the service's client.
-     * @param select The columns to select in the query (e.g., `"*"`, `"column1, column2"`).
+     * @param field The field to select distinct values for (e.g., `"field_name"`).
      * @param where The WHERE clause to filter the results (e.g., `"id = 1"`).
      * @param params Optional key-value substitutions applied to the WHERE clause (replaces $1, $2, etc.).
      * @returns A promise that resolves to an array of distinct values matching the query.
      */
-    distinct<T>(field: keyof T, where: string, params?: Record<string, number | string>): Promise<T[keyof T][]>;
+    distinct<K extends keyof T>(field: K, where: string, params?: Record<string, number | string>): Promise<T[K][]>;
     /**
      * Provides access to the ClickHouse client instance,
      * initializing it if it has not already been created.
@@ -64,7 +64,7 @@ export declare class ClickHouseInterfaceTemplate<T extends object> {
      * @param values An array of data objects to insert into the table.
      * @returns A promise that resolves when the data is inserted successfully.
      */
-    insert<T>(format: DataFormat | undefined, values: T[]): Promise<import("@clickhouse/client").InsertResult>;
+    insert(format: DataFormat | undefined, values: T[]): Promise<import("@clickhouse/client").InsertResult>;
     /**
      * Executes a simple SELECT query on the ClickHouse table using the service's client.
      * @param select The columns to select in the query (e.g., `"*"`, `"column1, column2"`).
@@ -98,7 +98,7 @@ export declare class ClickHouseInterfaceTemplate<T extends object> {
      *   end_date: '2024-12-31',
      * });
     */
-    queryFromFile<T>(filePath: string, params?: Record<string, number | string>): ReturnType<typeof queryFromFile<T>>;
+    queryFromFile(filePath: string, params?: Record<string, number | string>): ReturnType<typeof queryFromFile<T>>;
     /**
      * Executes a query from a string.
      * @param client The ClickHouse client to use for executing the query.
@@ -111,7 +111,7 @@ export declare class ClickHouseInterfaceTemplate<T extends object> {
      *   { start_date: '2024-01-01', end_date: '2024-12-31' }
      * );
     */
-    queryFromString<T>(query: string, params?: Record<string, number | string>): ReturnType<typeof queryFromString<T>>;
+    queryFromString(query: string, params?: Record<string, number | string>): ReturnType<typeof queryFromString<T>>;
     /**
      * Ensures that the specified database exists in ClickHouse, creating it if it does not already exist.
      * This method performs input validation to prevent SQL injection and logs the outcome of the operation.

package/dist/interface.template.js

@@ -53,14 +53,14 @@ export class ClickHouseInterfaceTemplate {
     }
     /**
      * Executes a DISTINCT query on the ClickHouse table using the service's client.
-     * @param select The columns to select in the query (e.g., `"*"`, `"column1, column2"`).
+     * @param field The field to select distinct values for (e.g., `"field_name"`).
      * @param where The WHERE clause to filter the results (e.g., `"id = 1"`).
      * @param params Optional key-value substitutions applied to the WHERE clause (replaces $1, $2, etc.).
      * @returns A promise that resolves to an array of distinct values matching the query.
      */
     async distinct(field, where, params) {
         const result = await queryFromString(this.client, `SELECT DISTINCT ${String(field)} FROM "${this.databaseName}"."${this.tableName}" WHERE ${where}`, params);
-        return result.map(doc => doc[field]);
+        return result;
     }
     /**
      * Provides access to the ClickHouse client instance,
@@ -180,8 +180,19 @@ export class ClickHouseInterfaceTemplate {
             throw new Error(`LABDB [${this.databaseName}]: Unsafe database name provided.`);
         // Perform the query to create the database if it does not exist
         try {
+            // First check if the database already exists
+            const result = await this.client.query({
+                query: `SELECT 1 FROM system.databases WHERE name = {name:String} LIMIT 1`,
+                query_params: { name: this.databaseName },
+            });
+            const resultData = await result.json();
+            const databaseAlreadyExists = resultData.data.length > 0;
+            // Always execute CREATE DATABASE IF NOT EXISTS to avoid race conditions
+            // if another instance creates the database after our existence check.
             await this.client.command({ query: `CREATE DATABASE IF NOT EXISTS "${this.databaseName}"` });
-            Logger.info({ message: `LABDB [${this.databaseName}]: Database created.` });
+            // Only log if the database did not exist when we checked.
+            if (!databaseAlreadyExists)
+                Logger.info({ message: `LABDB [${this.databaseName}]: Database created.` });
         }
         catch (error) {
             Logger.error({ error, message: `LABDB [${this.databaseName}]: Error @ createDatabase(): ${error.message}` });
@@ -220,8 +231,19 @@ export class ClickHouseInterfaceTemplate {
 		`;
         // Perform the query to create the table
         try {
+            // Check whether the table already exists.
+            const result = await this.client.query({
+                query: `SELECT 1 FROM system.tables WHERE database = {database:String} AND name = {table:String} LIMIT 1`,
+                query_params: { database: this.databaseName, table: this.tableName },
+            });
+            const resultData = await result.json();
+            const tableAlreadyExists = resultData.data.length > 0;
+            // Always execute CREATE TABLE IF NOT EXISTS to avoid race conditions
+            // if another instance creates the table after our existence check.
             await this.client.command({ query: createTableQuery });
-            Logger.info({ message: `LABDB [${this.tableName}]: Table created.` });
+            // Only log if the table did not exist when we checked.
+            if (!tableAlreadyExists)
+                Logger.info({ message: `LABDB [${this.tableName}]: Table created.` });
         }
         catch (error) {
             // If the error is not an ACCESS_DENIED, throw it right away

package/dist/schemas/operation.d.ts

@@ -1,3 +1,22 @@
 import { type ClickHouseTableSchema } from '@tmlmobilidade/go-clients-clickhouse';
+import { type HashedShape, type HashedTrip, type Ride, type RideAnalysisAtLeastOneVehicleEventOnFirstStop, type RideAnalysisAtLeastOneVehicleEventOnLastStop, type RideAnalysisExpectedApexValidationInterval, type RideAnalysisExpectedDriverIdQty, type RideAnalysisExpectedStartTime, type RideAnalysisExpectedVehicleEventDelay, type RideAnalysisExpectedVehicleEventInterval, type RideAnalysisExpectedVehicleEventQty, type RideAnalysisExpectedVehicleIdQty, type RideAnalysisMatchingApexLocations, type RideAnalysisMatchingVehicleIds, type RideAnalysisSimpleOneApexValidation, type RideAnalysisSimpleOneVehicleEventOrApexValidation, type RideAnalysisSimpleThreeVehicleEvents, type RideAnalysisTransactionSequentiality } from '@tmlmobilidade/go-types-operation';
 import { type SimplifiedVehicleEvent } from '@tmlmobilidade/go-types-vehicle-events';
 export declare const simplifiedVehicleEventTableSchema: ClickHouseTableSchema<SimplifiedVehicleEvent>;
+export declare const hashedShapeTableSchema: ClickHouseTableSchema<HashedShape>;
+export declare const hashedTripTableSchema: ClickHouseTableSchema<HashedTrip>;
+export declare const rideAnalysisAtLeastOneVehicleEventOnFirstStopTableSchema: ClickHouseTableSchema<RideAnalysisAtLeastOneVehicleEventOnFirstStop>;
+export declare const rideAnalysisAtLeastOneVehicleEventOnLastStopTableSchema: ClickHouseTableSchema<RideAnalysisAtLeastOneVehicleEventOnLastStop>;
+export declare const rideAnalysisExpectedApexValidationIntervalTableSchema: ClickHouseTableSchema<RideAnalysisExpectedApexValidationInterval>;
+export declare const rideAnalysisExpectedDriverIdQtyTableSchema: ClickHouseTableSchema<RideAnalysisExpectedDriverIdQty>;
+export declare const rideAnalysisExpectedStartTimeTableSchema: ClickHouseTableSchema<RideAnalysisExpectedStartTime>;
+export declare const rideAnalysisExpectedVehicleEventDelayTableSchema: ClickHouseTableSchema<RideAnalysisExpectedVehicleEventDelay>;
+export declare const rideAnalysisExpectedVehicleEventIntervalTableSchema: ClickHouseTableSchema<RideAnalysisExpectedVehicleEventInterval>;
+export declare const rideAnalysisExpectedVehicleEventQtyTableSchema: ClickHouseTableSchema<RideAnalysisExpectedVehicleEventQty>;
+export declare const rideAnalysisExpectedVehicleIdQtyTableSchema: ClickHouseTableSchema<RideAnalysisExpectedVehicleIdQty>;
+export declare const rideAnalysisMatchingApexLocationsTableSchema: ClickHouseTableSchema<RideAnalysisMatchingApexLocations>;
+export declare const rideAnalysisMatchingVehicleIdsTableSchema: ClickHouseTableSchema<RideAnalysisMatchingVehicleIds>;
+export declare const rideAnalysisSimpleOneApexValidationTableSchema: ClickHouseTableSchema<RideAnalysisSimpleOneApexValidation>;
+export declare const rideAnalysisSimpleOneVehicleEventOrApexValidationTableSchema: ClickHouseTableSchema<RideAnalysisSimpleOneVehicleEventOrApexValidation>;
+export declare const rideAnalysisSimpleThreeVehicleEventsTableSchema: ClickHouseTableSchema<RideAnalysisSimpleThreeVehicleEvents>;
+export declare const rideAnalysisTransactionSequentialityTableSchema: ClickHouseTableSchema<RideAnalysisTransactionSequentiality>;
+export declare const ridesTableSchema: ClickHouseTableSchema<Ride>;

package/dist/schemas/operation.js

@@ -19,3 +19,181 @@ export const simplifiedVehicleEventTableSchema = {
     trip_id: { type: 'String' },
     vehicle_id: { type: 'LowCardinality(String)' },
 };
+/* * */
+export const hashedShapeTableSchema = {
+    _id: { type: 'String' },
+    agency_id: { type: 'LowCardinality(String)' },
+    extension: { type: 'UInt32 CODEC(T64, ZSTD)' },
+    shape_id: { type: 'LowCardinality(String)' },
+    shape_polyline: { type: 'String CODEC(ZSTD)' },
+    updated_at: { type: 'Int64 CODEC(DoubleDelta, ZSTD)' },
+};
+/* * */
+export const hashedTripTableSchema = {
+    _id: { type: 'String' },
+    agency_id: { type: 'LowCardinality(String)' },
+    arrival_time: { type: 'FixedString(8)' },
+    departure_time: { type: 'FixedString(8)' },
+    drop_off_type: { type: 'FixedString(1)' },
+    pickup_type: { type: 'FixedString(1)' },
+    shape_dist_traveled: { type: 'Float32 CODEC(Gorilla, ZSTD)' },
+    shape_id: { type: 'LowCardinality(String)' },
+    stop_id: { type: 'LowCardinality(String)' },
+    stop_lat: { type: 'Float32 CODEC(Gorilla, ZSTD)' },
+    stop_lon: { type: 'Float32 CODEC(Gorilla, ZSTD)' },
+    stop_name: { type: 'String CODEC(ZSTD)' },
+    stop_sequence: { type: 'UInt16 CODEC(T64, ZSTD)' },
+    timepoint: { type: 'Bool' },
+    updated_at: { type: 'Int64 CODEC(DoubleDelta, ZSTD)' },
+};
+/* * */
+const rideAnalysisBaseTableSchema = {
+    agency_id: { type: 'LowCardinality(String)' },
+    grade_status: { type: 'LowCardinality(String)' },
+    operational_date: { type: 'UInt32' },
+    reason: { type: 'LowCardinality(Nullable(String))' },
+    remarks: { type: 'Nullable(String) CODEC(ZSTD)' },
+    ride_id: { type: 'String' },
+    updated_at: { type: 'Int64 CODEC(DoubleDelta, ZSTD)' },
+};
+/* * */
+export const rideAnalysisAtLeastOneVehicleEventOnFirstStopTableSchema = {
+    ...rideAnalysisBaseTableSchema,
+    vehicle_events_on_first_stop_qty: { type: 'Nullable(UInt16) CODEC(T64, ZSTD)' },
+};
+/* * */
+export const rideAnalysisAtLeastOneVehicleEventOnLastStopTableSchema = {
+    ...rideAnalysisBaseTableSchema,
+    vehicle_events_on_last_stop_qty: { type: 'Nullable(UInt16) CODEC(T64, ZSTD)' },
+};
+/* * */
+export const rideAnalysisExpectedApexValidationIntervalTableSchema = {
+    ...rideAnalysisBaseTableSchema,
+    observed_average_interval: { type: 'Nullable(UInt16) CODEC(T64, ZSTD)' },
+    observed_max_interval: { type: 'Nullable(UInt16) CODEC(T64, ZSTD)' },
+    observed_min_interval: { type: 'Nullable(UInt16) CODEC(T64, ZSTD)' },
+};
+/* * */
+export const rideAnalysisExpectedDriverIdQtyTableSchema = {
+    ...rideAnalysisBaseTableSchema,
+    observed_driver_ids_qty: { type: 'Nullable(UInt8) CODEC(T64, ZSTD)' },
+};
+/* * */
+export const rideAnalysisExpectedStartTimeTableSchema = {
+    ...rideAnalysisBaseTableSchema,
+    observed_start_time: { type: 'Nullable(Int64) CODEC(DoubleDelta, ZSTD)' },
+    observed_start_time_delta: { type: 'Nullable(Int16) CODEC(T64, ZSTD)' },
+};
+/* * */
+export const rideAnalysisExpectedVehicleEventDelayTableSchema = {
+    ...rideAnalysisBaseTableSchema,
+    observed_average_delay: { type: 'Nullable(UInt16) CODEC(T64, ZSTD)' },
+    observed_max_delay: { type: 'Nullable(UInt16) CODEC(T64, ZSTD)' },
+    observed_min_delay: { type: 'Nullable(UInt16) CODEC(T64, ZSTD)' },
+    vehicle_events_qty: { type: 'Nullable(UInt16) CODEC(T64, ZSTD)' },
+    vehicle_events_with_delay_percent: { type: 'Nullable(UInt8) CODEC(T64, ZSTD)' },
+    vehicle_events_with_delay_qty: { type: 'Nullable(UInt16) CODEC(T64, ZSTD)' },
+};
+/* * */
+export const rideAnalysisExpectedVehicleEventIntervalTableSchema = {
+    ...rideAnalysisBaseTableSchema,
+    observed_average_interval: { type: 'Nullable(UInt16) CODEC(T64, ZSTD)' },
+    observed_max_interval: { type: 'Nullable(UInt16) CODEC(T64, ZSTD)' },
+    observed_min_interval: { type: 'Nullable(UInt16) CODEC(T64, ZSTD)' },
+};
+/* * */
+export const rideAnalysisExpectedVehicleEventQtyTableSchema = {
+    ...rideAnalysisBaseTableSchema,
+    expected_vehicle_events_qty: { type: 'Nullable(UInt16) CODEC(T64, ZSTD)' },
+    observed_vehicle_events_qty: { type: 'Nullable(UInt16) CODEC(T64, ZSTD)' },
+};
+/* * */
+export const rideAnalysisExpectedVehicleIdQtyTableSchema = {
+    ...rideAnalysisBaseTableSchema,
+    observed_vehicle_ids_qty: { type: 'Nullable(UInt8) CODEC(T64, ZSTD)' },
+};
+/* * */
+export const rideAnalysisMatchingApexLocationsTableSchema = {
+    ...rideAnalysisBaseTableSchema,
+    expected_apex_locations_qty: { type: 'Nullable(UInt16) CODEC(T64, ZSTD)' },
+    matching_apex_locations_qty: { type: 'Nullable(UInt16) CODEC(T64, ZSTD)' },
+    missing_apex_locations_qty: { type: 'Nullable(UInt16) CODEC(T64, ZSTD)' },
+};
+/* * */
+export const rideAnalysisMatchingVehicleIdsTableSchema = {
+    ...rideAnalysisBaseTableSchema,
+    extra_apex_vehicle_ids_qty: { type: 'Nullable(UInt8) CODEC(T64, ZSTD)' },
+    extra_vehicle_events_vehicle_ids_qty: { type: 'Nullable(UInt8) CODEC(T64, ZSTD)' },
+    matching_vehicle_ids_qty: { type: 'Nullable(UInt8) CODEC(T64, ZSTD)' },
+    total_vehicle_ids_qty: { type: 'Nullable(UInt8) CODEC(T64, ZSTD)' },
+};
+/* * */
+export const rideAnalysisSimpleOneApexValidationTableSchema = {
+    ...rideAnalysisBaseTableSchema,
+};
+/* * */
+export const rideAnalysisSimpleOneVehicleEventOrApexValidationTableSchema = {
+    ...rideAnalysisBaseTableSchema,
+};
+/* * */
+export const rideAnalysisSimpleThreeVehicleEventsTableSchema = {
+    ...rideAnalysisBaseTableSchema,
+    stop_ids_first: { type: 'Array(LowCardinality(String))' },
+    stop_ids_last: { type: 'Array(LowCardinality(String))' },
+    stop_ids_middle: { type: 'Array(LowCardinality(String))' },
+};
+/* * */
+export const rideAnalysisTransactionSequentialityTableSchema = {
+    ...rideAnalysisBaseTableSchema,
+    expected_transactions_qty: { type: 'Nullable(UInt16) CODEC(T64, ZSTD)' },
+    found_transactions_qty: { type: 'Nullable(UInt16) CODEC(T64, ZSTD)' },
+    missing_transactions_qty: { type: 'Nullable(UInt16) CODEC(T64, ZSTD)' },
+};
+/* * */
+export const ridesTableSchema = {
+    _id: { type: 'String' },
+    agency_code: { type: 'LowCardinality(String)' },
+    agency_id: { type: 'LowCardinality(String)' },
+    apex_banking_taps_amount: { type: 'Nullable(Int32) CODEC(T64, ZSTD)' },
+    apex_banking_taps_qty: { type: 'Nullable(UInt16) CODEC(T64, ZSTD)' },
+    apex_locations_qty: { type: 'Nullable(UInt16) CODEC(T64, ZSTD)' },
+    apex_refunds_amount: { type: 'Nullable(Int32) CODEC(T64, ZSTD)' },
+    apex_refunds_qty: { type: 'Nullable(UInt16) CODEC(T64, ZSTD)' },
+    apex_sales_amount: { type: 'Nullable(Int32) CODEC(T64, ZSTD)' },
+    apex_sales_qty: { type: 'Nullable(UInt16) CODEC(T64, ZSTD)' },
+    apex_validations_qty: { type: 'Nullable(UInt16) CODEC(T64, ZSTD)' },
+    direction_id: { type: 'FixedString(1)' },
+    driver_ids: { type: 'Array(LowCardinality(String))' },
+    end_time_observed: { type: 'Nullable(Int64) CODEC(DoubleDelta, ZSTD)' },
+    end_time_scheduled: { type: 'Int64 CODEC(DoubleDelta, ZSTD)' },
+    extension_observed: { type: 'Nullable(UInt32) CODEC(T64, ZSTD)' },
+    extension_scheduled: { type: 'UInt32 CODEC(T64, ZSTD)' },
+    hashed_shape_id: { type: 'LowCardinality(String)' },
+    hashed_trip_id: { type: 'LowCardinality(String)' },
+    headsign: { type: 'LowCardinality(String)' },
+    operational_date: { type: 'UInt32' },
+    passengers_estimated: { type: 'Nullable(UInt32) CODEC(T64, ZSTD)' },
+    passengers_observed: { type: 'Nullable(UInt32) CODEC(T64, ZSTD)' },
+    passengers_observed_banking_taps_amount: { type: 'Nullable(Int32) CODEC(T64, ZSTD)' },
+    passengers_observed_banking_taps_qty: { type: 'Nullable(UInt16) CODEC(T64, ZSTD)' },
+    passengers_observed_prepaid_amount: { type: 'Nullable(Int32) CODEC(T64, ZSTD)' },
+    passengers_observed_prepaid_qty: { type: 'Nullable(UInt16) CODEC(T64, ZSTD)' },
+    passengers_observed_sales_amount: { type: 'Nullable(Int32) CODEC(T64, ZSTD)' },
+    passengers_observed_sales_qty: { type: 'Nullable(UInt16) CODEC(T64, ZSTD)' },
+    passengers_observed_subscription_qty: { type: 'Nullable(UInt16) CODEC(T64, ZSTD)' },
+    plan_id: { type: 'LowCardinality(String)' },
+    processing_status: { type: 'LowCardinality(String)' },
+    route_color: { type: 'FixedString(7)' },
+    route_id: { type: 'LowCardinality(String)' },
+    route_long_name: { type: 'LowCardinality(String)' },
+    route_short_name: { type: 'LowCardinality(String)' },
+    route_text_color: { type: 'FixedString(7)' },
+    seen_first_at: { type: 'Nullable(Int64) CODEC(DoubleDelta, ZSTD)' },
+    seen_last_at: { type: 'Nullable(Int64) CODEC(DoubleDelta, ZSTD)' },
+    shape_id: { type: 'LowCardinality(String)' },
+    start_time_observed: { type: 'Nullable(Int64) CODEC(DoubleDelta, ZSTD)' },
+    start_time_scheduled: { type: 'Int64 CODEC(DoubleDelta, ZSTD)' },
+    trip_id: { type: 'LowCardinality(String)' },
+    updated_at: { type: 'Int64 CODEC(DoubleDelta, ZSTD)' },
+    vehicle_ids: { type: 'Array(LowCardinality(String))' },
+};

package/dist/schemas/simplified-apex.d.ts

@@ -1,5 +1,5 @@
 import { type ClickHouseTableSchema } from '@tmlmobilidade/go-clients-clickhouse';
-import { type SimplifiedApexBankingTap, SimplifiedApexInspection, SimplifiedApexInspectionDecision, SimplifiedApexLocation, SimplifiedApexOnBoardRefund, SimplifiedApexOnBoardSale, SimplifiedApexValidation } from '@tmlmobilidade/go-types-apex';
+import { type SimplifiedApexBankingTap, type SimplifiedApexInspection, type SimplifiedApexInspectionDecision, type SimplifiedApexLocation, type SimplifiedApexOnBoardRefund, type SimplifiedApexOnBoardSale, type SimplifiedApexValidation } from '@tmlmobilidade/go-types-apex';
 export declare const simplifiedApexBankingTapTableSchema: ClickHouseTableSchema<SimplifiedApexBankingTap>;
 export declare const simplifiedApexInspectionDecisionTableSchema: ClickHouseTableSchema<SimplifiedApexInspectionDecision>;
 export declare const simplifiedApexInspectionTableSchema: ClickHouseTableSchema<SimplifiedApexInspection>;

package/dist/schemas/simplified-apex.js

@@ -5,6 +5,7 @@ export const simplifiedApexBankingTapTableSchema = {
     agency_code: { type: 'LowCardinality(String)' },
     agency_id: { type: 'LowCardinality(String)' },
     apex_version: { type: 'LowCardinality(String)' },
+    banking_tap_id: { type: 'String' },
     banking_token: { type: 'String' },
     card_brand: { type: 'UInt8' },
     card_pan: { type: 'String' },

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@tmlmobilidade/go-interfaces-labdb",
-	"version": "20260811.1505.45",
+	"version": "20260828.1636.54",
 	"author": {
 		"email": "iso@tmlmobilidade.pt",
 		"name": "TML-ISO"
@@ -38,14 +38,14 @@
 	"dependencies": {
 		"@tmlmobilidade/go-clients-clickhouse": "*",
 		"@tmlmobilidade/go-types-apex": "*",
+		"@tmlmobilidade/go-types-operation": "*",
 		"@tmlmobilidade/go-types-performance": "*",
 		"@tmlmobilidade/go-types-vehicle-events": "*",
 		"@tmlmobilidade/logger": "*",
-		"@tmlmobilidade/types": "*",
 		"@tmlmobilidade/utils": "*"
 	},
 	"devDependencies": {
-		"@tmlmobilidade/tsconfig": "*",
+		"@tmlmobilidade/go-utils-tsconfig": "*",
 		"@types/node": "26.1.2",
 		"resolve-tspaths": "0.8.23",
 		"tsc-watch": "7.2.1",