From 6932511f41abeb87449be1e52d1140a5a1ab8a2a Mon Sep 17 00:00:00 2001 From: Yvonne Pan <103622026+yvonnep165@users.noreply.github.com> Date: Thu, 19 Mar 2026 14:14:45 -0400 Subject: [PATCH 1/5] Add timestampTrunc, timestampDiff and timestampExtract expressions --- .../firestore/api-report/firestore.api.md | 30 ++ .../firestore/dev/src/pipelines/expression.ts | 340 +++++++++++++++++- .../firestore/dev/src/pipelines/index.ts | 2 + .../firestore/dev/system-test/pipeline.ts | 75 ++++ handwritten/firestore/types/firestore.d.ts | 289 ++++++++++++++- 5 files changed, 728 insertions(+), 8 deletions(-) diff --git a/handwritten/firestore/api-report/firestore.api.md b/handwritten/firestore/api-report/firestore.api.md index 06f0a189578..13a4ba92239 100644 --- a/handwritten/firestore/api-report/firestore.api.md +++ b/handwritten/firestore/api-report/firestore.api.md @@ -1207,6 +1207,10 @@ abstract class Expression implements firestore.Pipelines.Expression, HasUserData sum(): AggregateFunction; timestampAdd(unit: Expression, amount: Expression): FunctionExpression; timestampAdd(unit: 'microsecond' | 'millisecond' | 'second' | 'minute' | 'hour' | 'day', amount: number): FunctionExpression; + timestampDiff(start: Expression, unit: Expression): FunctionExpression; + timestampDiff(start: string | Expression, unit: 'microsecond' | 'millisecond' | 'second' | 'minute' | 'hour' | 'day'): FunctionExpression; + timestampExtract(part: firestore.Pipelines.TimePart, timezone?: string | Expression): FunctionExpression; + timestampExtract(part: Expression, timezone?: string | Expression): FunctionExpression; timestampSubtract(unit: Expression, amount: Expression): FunctionExpression; timestampSubtract(unit: 'microsecond' | 'millisecond' | 'second' | 'minute' | 'hour' | 'day', amount: number): FunctionExpression; timestampToUnixMicros(): FunctionExpression; @@ -2113,6 +2117,8 @@ declare namespace Pipelines { isType, Type, timestampTruncate, + timestampExtract, + timestampDiff, split, ltrim, rtrim, @@ -2701,6 +2707,30 @@ function timestampAdd(timestamp: Expression, unit: 'microsecond' | 'millisecond' // @beta function timestampAdd(fieldName: string, unit: 'microsecond' | 'millisecond' | 'second' | 'minute' | 'hour' | 'day', amount: number): FunctionExpression; +// @beta +function timestampDiff(endFieldName: string, startFieldName: string, unit: 'microsecond' | 'millisecond' | 'second' | 'minute' | 'hour' | 'day' | Expression): FunctionExpression; + +// @beta +function timestampDiff(endFieldName: string, startExpression: Expression, unit: 'microsecond' | 'millisecond' | 'second' | 'minute' | 'hour' | 'day' | Expression): FunctionExpression; + +// @beta +function timestampDiff(endExpression: Expression, startFieldName: string, unit: 'microsecond' | 'millisecond' | 'second' | 'minute' | 'hour' | 'day' | Expression): FunctionExpression; + +// @beta +function timestampDiff(endExpression: Expression, startExpression: Expression, unit: 'microsecond' | 'millisecond' | 'second' | 'minute' | 'hour' | 'day' | Expression): FunctionExpression; + +// @beta +function timestampExtract(fieldName: string, part: firestore.Pipelines.TimePart, timezone?: string | Expression): FunctionExpression; + +// @beta +function timestampExtract(fieldName: string, part: Expression, timezone?: string | Expression): FunctionExpression; + +// @beta +function timestampExtract(timestampExpression: Expression, part: firestore.Pipelines.TimePart, timezone?: string | Expression): FunctionExpression; + +// @beta +function timestampExtract(timestampExpression: Expression, part: Expression, timezone?: string | Expression): FunctionExpression; + // @beta function timestampSubtract(timestamp: Expression, unit: Expression, amount: Expression): FunctionExpression; diff --git a/handwritten/firestore/dev/src/pipelines/expression.ts b/handwritten/firestore/dev/src/pipelines/expression.ts index 20054a59b81..bfb52eb707e 100644 --- a/handwritten/firestore/dev/src/pipelines/expression.ts +++ b/handwritten/firestore/dev/src/pipelines/expression.ts @@ -2429,6 +2429,111 @@ export abstract class Expression ]); } + /** + * @beta + * Creates an expression that calculates the difference between this timestamp and another timestamp. + * + * @example + * ```typescript + * // Calculate the difference determined by fields 'startTime' and 'unit'. + * field("endTime").timestampDiff(field("startTime"), field("unit")); + * ``` + * + * @param start - The expression evaluating to the starting timestamp. + * @param unit - The expression evaluates to a unit of time, must be one of 'microsecond', 'millisecond', 'second', 'minute', 'hour', 'day'. + * @returns A new `Expression` representing the difference as an integer. + */ + timestampDiff(start: Expression, unit: Expression): FunctionExpression; + + /** + * @beta + * Creates an expression that calculates the difference between this timestamp and another timestamp. + * + * @example + * ```typescript + * // Calculate the difference in days between 'endTime' and 'startTime' fields. + * field("endTime").timestampDiff("startTime", "day"); + * ``` + * + * @param start - The field name of the starting timestamp. + * @param unit - The unit of time for the difference (e.g., "day", "hour"). + * @returns A new `Expression` representing the difference as an integer. + */ + timestampDiff( + start: string | Expression, + unit: 'microsecond' | 'millisecond' | 'second' | 'minute' | 'hour' | 'day' + ): FunctionExpression; + timestampDiff( + start: string | Expression, + unit: + | 'microsecond' + | 'millisecond' + | 'second' + | 'minute' + | 'hour' + | 'day' + | Expression + ): FunctionExpression { + return new FunctionExpression( + 'timestamp_diff', + [this, fieldOrExpression(start), valueToDefaultExpr(unit)], + ); + } + + /** + * @beta + * Creates an expression that extracts a specified part from this timestamp expression. + * + * @example + * ```typescript + * // Extract the year from the 'createdAt' field. + * field('createdAt').timestampExtract('year') + * ``` + * + * @param part - The part to extract from the timestamp (e.g., "year", "month", "day"). + * @param timezone - The timezone to use for extraction. Valid values are from + * the TZ database (e.g., "America/Los_Angeles") or in the format "Etc/GMT-1." + * @returns A new `Expression` representing the extracted part as an integer. + */ + timestampExtract( + part: firestore.Pipelines.TimePart, + timezone?: string | Expression + ): FunctionExpression; + + /** + * @beta + * Creates an expression that extracts a specified part from this timestamp expression. + * + * @example + * ```typescript + * // Extract the part specified by the field 'extractionPart' from 'createdAt'. + * field('createdAt').timestampExtract(field('extractionPart')) + * ``` + * + * @param part - The expression evaluating to the part to extract. + * @param timezone - The timezone to use for extraction. Valid values are from + * the TZ database (e.g., "America/Los_Angeles") or in the format "Etc/GMT-1." + * @returns A new `Expression` representing the extracted part as an integer. + */ + timestampExtract( + part: Expression, + timezone?: string | Expression + ): FunctionExpression; + timestampExtract( + part: firestore.Pipelines.TimePart | Expression, + timezone?: string | Expression + ): FunctionExpression { + const internalPart = isString(part) ? part.toLowerCase() : part; + const args = [this, valueToDefaultExpr(internalPart)]; + if (timezone) { + args.push(valueToDefaultExpr(timezone)); + } + return new FunctionExpression( + 'timestamp_extract', + args, + ); + } + /** * @beta * Creates an expression that returns the document ID from a path. @@ -9382,7 +9487,7 @@ export function split( * @example * ```typescript * // Truncate the 'createdAt' timestamp to the beginning of the day. - * field('createdAt').timestampTruncate('day') + * timestampTruncate('createdAt', 'day') * ``` * * @param fieldName Truncate the timestamp value contained in this field. @@ -9403,7 +9508,7 @@ export function timestampTruncate( * @example * ```typescript * // Truncate the 'createdAt' timestamp to the granularity specified in the field 'granularity'. - * field('createdAt').timestampTruncate(field('granularity')) + * timestampTruncate('createdAt', field('granularity')) * ``` * * @param fieldName Truncate the timestamp value contained in this field. @@ -9424,7 +9529,7 @@ export function timestampTruncate( * @example * ```typescript * // Truncate the 'createdAt' timestamp to the beginning of the day. - * field('createdAt').timestampTruncate('day') + * timestampTruncate(field('createdAt'), 'day') * ``` * * @param timestampExpression Truncate the timestamp value that is returned by this expression. @@ -9445,7 +9550,7 @@ export function timestampTruncate( * @example * ```typescript * // Truncate the 'createdAt' timestamp to the granularity specified in the field 'granularity'. - * field('createdAt').timestampTruncate(field('granularity')) + * timestampTruncate(field('createdAt'), field('granularity')) * ``` * * @param timestampExpression Truncate the timestamp value that is returned by this expression. @@ -9473,6 +9578,233 @@ export function timestampTruncate( ); } +/** + * @beta + * Creates an expression that calculates the difference between two timestamps. + * + * @example + * ```typescript + * // Calculate the difference in days between 'endTime' and 'startTime' fields. + * timestampDiff('endTime', 'startTime', 'day') + * ``` + * + * @param endFieldName - The name of the field representing the ending timestamp. + * @param startFieldName - The name of the field representing the starting timestamp. + * @param unit - The unit of time for the difference (e.g., "day", "hour"). + * @returns A new `Expression` representing the difference as an integer. + */ +export function timestampDiff( + endFieldName: string, + startFieldName: string, + unit: + | 'microsecond' + | 'millisecond' + | 'second' + | 'minute' + | 'hour' + | 'day' + | Expression +): FunctionExpression; + +/** + * @beta + * Creates an expression that calculates the difference between two timestamps. + * + * @example + * ```typescript + * // Calculate the difference in days between 'endTime' field and a starting timestamp expression. + * timestampDiff('endTime', field('startTime'), 'day') + * ``` + * + * @param endFieldName - The name of the field representing the ending timestamp. + * @param startExpression - The starting timestamp for the difference calculation. + * @param unit - The unit of time for the difference (e.g., "day", "hour"). + * @returns A new `Expression` representing the difference as an integer. + */ +export function timestampDiff( + endFieldName: string, + startExpression: Expression, + unit: + | 'microsecond' + | 'millisecond' + | 'second' + | 'minute' + | 'hour' + | 'day' + | Expression +): FunctionExpression; + +/** + * @beta + * Creates an expression that calculates the difference between two timestamps. + * + * @example + * ```typescript + * // Calculate the difference in days between an ending timestamp expression and 'startTime' field. + * timestampDiff(field('endTime'), 'startTime', 'day') + * ``` + * + * @param endExpression - The ending timestamp for the difference calculation. + * @param startFieldName - The name of the field representing the starting timestamp. + * @param unit - The unit of time for the difference (e.g., "day", "hour"). + * @returns A new `Expression` representing the difference as an integer. + */ +export function timestampDiff( + endExpression: Expression, + startFieldName: string, + unit: + | 'microsecond' + | 'millisecond' + | 'second' + | 'minute' + | 'hour' + | 'day' + | Expression +): FunctionExpression; + +/** + * @beta + * Creates an expression that calculates the difference between two timestamps. + * + * @example + * ```typescript + * // Calculate the difference in days between two timestamp expressions. + * timestampDiff(field('endTime'), field('startTime'), 'day') + * ``` + * + * @param endExpression - The ending timestamp for the difference calculation. + * @param startExpression - The starting timestamp for the difference calculation. + * @param unit - The unit of time for the difference (e.g., "day", "hour"). + * @returns A new `Expression` representing the difference as an integer. + */ +export function timestampDiff( + endExpression: Expression, + startExpression: Expression, + unit: + | 'microsecond' + | 'millisecond' + | 'second' + | 'minute' + | 'hour' + | 'day' + | Expression +): FunctionExpression; +export function timestampDiff( + endFieldNameOrExpression: string | Expression, + startFieldNameOrExpression: string | Expression, + unit: + | 'microsecond' + | 'millisecond' + | 'second' + | 'minute' + | 'hour' + | 'day' + | Expression +): FunctionExpression { + const normalizedEnd = fieldOrExpression(endFieldNameOrExpression); + const normalizedStart = fieldOrExpression(startFieldNameOrExpression); + const normalizedUnit = valueToDefaultExpr(unit); + return normalizedEnd.timestampDiff(normalizedStart, normalizedUnit); +} + +/** + * @beta + * Creates an expression that extracts a specified part from a timestamp. + * + * @example + * ```typescript + * // Extract the year from the 'createdAt' timestamp. + * timestampExtract('createdAt', 'year') + * ``` + * + * @param fieldName - The name of the field representing the timestamp. + * @param part - The part to extract from the timestamp (e.g., "year", "month", "day"). + * @param timezone - The timezone to use for extraction. Valid values are from + * the TZ database (e.g., "America/Los_Angeles") or in the format "Etc/GMT-1." + * @returns A new `Expression` representing the extracted part as an integer. + */ +export function timestampExtract( + fieldName: string, + part: firestore.Pipelines.TimePart, + timezone?: string | Expression +): FunctionExpression; + +/** + * @beta + * Creates an expression that extracts a specified part from a timestamp. + * + * @example + * ```typescript + * // Extract the part specified by the field 'part' from 'createdAt'. + * timestampExtract('createdAt', field('part')) + * ``` + * + * @param fieldName - The name of the field representing the timestamp. + * @param part - The expression evaluating to the part to extract. + * @param timezone - The timezone to use for extraction. Valid values are from + * the TZ database (e.g., "America/Los_Angeles") or in the format "Etc/GMT-1." + * @returns A new `Expression` representing the extracted part as an integer. + */ +export function timestampExtract( + fieldName: string, + part: Expression, + timezone?: string | Expression +): FunctionExpression; + +/** + * @beta + * Creates an expression that extracts a specified part from a timestamp. + * + * @example + * ```typescript + * // Extract the year from the timestamp returned by the expression. + * timestampExtract(field('createdAt'), 'year') + * ``` + * + * @param timestampExpression - The expression evaluating to the timestamp. + * @param part - The part to extract from the timestamp (e.g., "year", "month", "day"). + * @param timezone - The timezone to use for extraction. Valid values are from + * the TZ database (e.g., "America/Los_Angeles") or in the format "Etc/GMT-1." + * @returns A new `Expression` representing the extracted part as an integer. + */ +export function timestampExtract( + timestampExpression: Expression, + part: firestore.Pipelines.TimePart, + timezone?: string | Expression +): FunctionExpression; + +/** + * @beta + * Creates an expression that extracts a specified part from a timestamp. + * + * @example + * ```typescript + * // Extract the part specified by the field 'part' from the timestamp. + * timestampExtract(field('createdAt'), field('part')) + * ``` + * + * @param timestampExpression - The expression evaluating to the timestamp. + * @param part - The expression evaluating to the part to extract. + * @param timezone - The timezone to use for extraction. Valid values are from + * the TZ database (e.g., "America/Los_Angeles") or in the format "Etc/GMT-1." + * @returns A new `Expression` representing the extracted part as an integer. + */ +export function timestampExtract( + timestampExpression: Expression, + part: Expression, + timezone?: string | Expression +): FunctionExpression; +export function timestampExtract( + fieldNameOrExpression: string | Expression, + part: firestore.Pipelines.TimePart | Expression, + timezone?: string | Expression +): FunctionExpression { + return fieldOrExpression(fieldNameOrExpression).timestampExtract( + valueToDefaultExpr(isString(part) ? part.toLowerCase() : part), + timezone + ); +} + /** * @beta * Creates an expression that returns the data type of the data in the specified field. diff --git a/handwritten/firestore/dev/src/pipelines/index.ts b/handwritten/firestore/dev/src/pipelines/index.ts index e0bc969104c..f27dbcef6ed 100644 --- a/handwritten/firestore/dev/src/pipelines/index.ts +++ b/handwritten/firestore/dev/src/pipelines/index.ts @@ -148,6 +148,8 @@ export { isType, Type, timestampTruncate, + timestampExtract, + timestampDiff, split, ltrim, rtrim, diff --git a/handwritten/firestore/dev/system-test/pipeline.ts b/handwritten/firestore/dev/system-test/pipeline.ts index 7bdb4405b17..d56aab17556 100644 --- a/handwritten/firestore/dev/system-test/pipeline.ts +++ b/handwritten/firestore/dev/system-test/pipeline.ts @@ -147,6 +147,8 @@ import { type, isType, timestampTruncate, + timestampExtract, + timestampDiff, split, // TODO(new-expression): add new expression imports above this line } from '../src/pipelines'; @@ -5052,6 +5054,79 @@ describe.skipClassic('Pipeline class', () => { }); }); + it('supports timestamp difference', async () => { + const results = await firestore + .pipeline() + .collection(randomCol.path) + .limit(1) + .replaceWith( + map({ + end: new Timestamp(1741437296, 123456789), + start: new Timestamp(1741428000, 0), + }), + ) + .select( + timestampDiff(field('end'), field('start'), 'hour').as('diffHour'), + field('end') + .timestampDiff(field('start'), 'minute') + .as('diffMinute'), + field('end') + .timestampDiff(field('start'), 'second') + .as('diffSecond'), + field('start') + .timestampDiff(field('end'), 'hour') + .as('diffHourNeg'), + ) + .execute(); + + expectResults(results, { + diffHour: 2, + diffMinute: 154, + diffSecond: 9296, + diffHourNeg: -2, + }); + }); + + it('supports timestamp extraction', async () => { + const results = await firestore + .pipeline() + .collection(randomCol.path) + .limit(1) + .replaceWith( + map({ + ts: new Timestamp(1741437296, 123456789), + }), + ) + .select( + timestampExtract(field('ts'), 'year').as('year'), + field('ts').timestampExtract('month').as('month'), + timestampExtract(field('ts'), 'day').as('day'), + field('ts').timestampExtract('hour').as('hour'), + timestampExtract(field('ts'), 'minute').as('minute'), + field('ts').timestampExtract('second').as('second'), + timestampExtract(field('ts'), 'millisecond').as('millis'), + field('ts').timestampExtract('microsecond').as('micros'), + timestampExtract(field('ts'), 'dayofyear').as('dayOfYear'), + field('ts') + .timestampExtract('hour', 'America/Los_Angeles') + .as('hourLa'), + ) + .execute(); + + expectResults(results, { + year: 2025, + month: 3, + day: 8, + hour: 12, + minute: 34, + second: 56, + millis: 123, + micros: 123456, + dayOfYear: 67, + hourLa: 4, + }); + }); + it('supports split', async () => { const results = await firestore .pipeline() diff --git a/handwritten/firestore/types/firestore.d.ts b/handwritten/firestore/types/firestore.d.ts index e58444a2053..4ebe8b84b2e 100644 --- a/handwritten/firestore/types/firestore.d.ts +++ b/handwritten/firestore/types/firestore.d.ts @@ -5572,6 +5572,81 @@ declare namespace FirebaseFirestore { timezone?: string | Expression, ): FunctionExpression; + /** + * @beta + * Creates an expression that calculates the difference between this timestamp and another timestamp. + * + * @example + * ```typescript + * // Calculate the difference determined by fields 'startTime' and 'unit'. + * field("endTime").timestampDiff(field("startTime"), field("unit")); + * ``` + * + * @param start - The expression evaluating to the starting timestamp. + * @param unit - The expression evaluates to a unit of time, must be one of 'microsecond', 'millisecond', 'second', 'minute', 'hour', 'day'. + * @returns A new `Expression` representing the difference as an integer. + */ + timestampDiff(start: Expression, unit: Expression): FunctionExpression; + + /** + * @beta + * Creates an expression that calculates the difference between this timestamp and another timestamp. + * + * @example + * ```typescript + * // Calculate the difference in days between 'endTime' and 'startTime' fields. + * field("endTime").timestampDiff("startTime", "day"); + * ``` + * + * @param start - The field name of the starting timestamp. + * @param unit - The unit of time for the difference (e.g., "day", "hour"). + * @returns A new `Expression` representing the difference as an integer. + */ + timestampDiff( + start: string | Expression, + unit: 'microsecond' | 'millisecond' | 'second' | 'minute' | 'hour' | 'day' + ): FunctionExpression; + + /** + * @beta + * Creates an expression that extracts a specified part from this timestamp expression. + * + * @example + * ```typescript + * // Extract the year from the 'createdAt' field. + * field('createdAt').timestampExtract('year') + * ``` + * + * @param part - The part to extract from the timestamp (e.g., "year", "month", "day"). + * @param timezone - The timezone to use for extraction. Valid values are from + * the TZ database (e.g., "America/Los_Angeles") or in the format "Etc/GMT-1." + * @returns A new `Expression` representing the extracted part as an integer. + */ + timestampExtract( + part: TimePart, + timezone?: string | Expression + ): FunctionExpression; + + /** + * @beta + * Creates an expression that extracts a specified part from this timestamp expression. + * + * @example + * ```typescript + * // Extract the part specified by the field 'extractionPart' from 'createdAt'. + * field('createdAt').timestampExtract(field('extractionPart')) + * ``` + * + * @param part - The expression evaluating to the part to extract. + * @param timezone - The timezone to use for extraction. Valid values are from + * the TZ database (e.g., "America/Los_Angeles") or in the format "Etc/GMT-1." + * @returns A new `Expression` representing the extracted part as an integer. + */ + timestampExtract( + part: Expression, + timezone?: string | Expression + ): FunctionExpression; + /** * @beta * Creates an expression that returns the data type of this expression's result, as a string. @@ -5678,6 +5753,12 @@ declare namespace FirebaseFirestore { | 'year' | 'isoYear'; + /** + * @beta + * Specify time parts for `timestampExtract` expressions. + */ + export type TimePart = TimeGranularity | 'dayofweek' | 'dayofyear'; + /** * @beta * An interface that represents a selectable expression. @@ -11200,7 +11281,7 @@ declare namespace FirebaseFirestore { * @example * ```typescript * // Truncate the 'createdAt' timestamp to the beginning of the day. - * field('createdAt').timestampTruncate('day') + * timestampTruncate('createdAt', 'day') * ``` * * @param fieldName Truncate the timestamp value contained in this field. @@ -11221,7 +11302,7 @@ declare namespace FirebaseFirestore { * @example * ```typescript * // Truncate the 'createdAt' timestamp to the granularity specified in the field 'granularity'. - * field('createdAt').timestampTruncate(field('granularity')) + * timestampTruncate('createdAt', field('granularity')) * ``` * * @param fieldName Truncate the timestamp value contained in this field. @@ -11242,7 +11323,7 @@ declare namespace FirebaseFirestore { * @example * ```typescript * // Truncate the 'createdAt' timestamp to the beginning of the day. - * field('createdAt').timestampTruncate('day') + * timestampTruncate(field('createdAt'), 'day') * ``` * * @param timestampExpression Truncate the timestamp value that is returned by this expression. @@ -11263,7 +11344,7 @@ declare namespace FirebaseFirestore { * @example * ```typescript * // Truncate the 'createdAt' timestamp to the granularity specified in the field 'granularity'. - * field('createdAt').timestampTruncate(field('granularity')) + * timestampTruncate(field('createdAt'), field('granularity') * ``` * * @param timestampExpression Truncate the timestamp value that is returned by this expression. @@ -11278,6 +11359,206 @@ declare namespace FirebaseFirestore { timezone?: string | Expression, ): FunctionExpression; + /** + * @beta + * Creates an expression that calculates the difference between two timestamps. + * + * @example + * ```typescript + * // Calculate the difference in days between 'endTime' and 'startTime' fields. + * timestampDiff('endTime', 'startTime', 'day') + * ``` + * + * @param endFieldName - The name of the field representing the ending timestamp. + * @param startFieldName - The name of the field representing the starting timestamp. + * @param unit - The unit of time for the difference (e.g., "day", "hour"). + * @returns A new {@code Expression} representing the difference as an integer. + */ + export function timestampDiff( + endFieldName: string, + startFieldName: string, + unit: + | 'microsecond' + | 'millisecond' + | 'second' + | 'minute' + | 'hour' + | 'day' + | Expression + ): FunctionExpression; + + /** + * @beta + * Creates an expression that calculates the difference between two timestamps. + * + * @example + * ```typescript + * // Calculate the difference in days between 'endTime' field and a starting timestamp expression. + * timestampDiff('endTime', field('startTime'), 'day') + * ``` + * + * @param endFieldName - The name of the field representing the ending timestamp. + * @param startExpression - The starting timestamp for the difference calculation. + * @param unit - The unit of time for the difference (e.g., "day", "hour"). + * @returns A new {@code Expression} representing the difference as an integer. + */ + export function timestampDiff( + endFieldName: string, + startExpression: Expression, + unit: + | 'microsecond' + | 'millisecond' + | 'second' + | 'minute' + | 'hour' + | 'day' + | Expression + ): FunctionExpression; + + /** + * @beta + * Creates an expression that calculates the difference between two timestamps. + * + * @example + * ```typescript + * // Calculate the difference in days between an ending timestamp expression and 'startTime' field. + * timestampDiff(field('endTime'), 'startTime', 'day') + * ``` + * + * @param endExpression - The ending timestamp for the difference calculation. + * @param startFieldName - The name of the field representing the starting timestamp. + * @param unit - The unit of time for the difference (e.g., "day", "hour"). + * @returns A new {@code Expression} representing the difference as an integer. + */ + export function timestampDiff( + endExpression: Expression, + startFieldName: string, + unit: + | 'microsecond' + | 'millisecond' + | 'second' + | 'minute' + | 'hour' + | 'day' + | Expression + ): FunctionExpression; + + /** + * @beta + * Creates an expression that calculates the difference between two timestamps. + * + * @example + * ```typescript + * // Calculate the difference in days between two timestamp expressions. + * timestampDiff(field('endTime'), field('startTime'), 'day') + * ``` + * + * @param endExpression - The ending timestamp for the difference calculation. + * @param startExpression - The starting timestamp for the difference calculation. + * @param unit - The unit of time for the difference (e.g., "day", "hour"). + * @returns A new {@code Expression} representing the difference as an integer. + */ + export function timestampDiff( + endExpression: Expression, + startExpression: Expression, + unit: + | 'microsecond' + | 'millisecond' + | 'second' + | 'minute' + | 'hour' + | 'day' + | Expression + ): FunctionExpression; + + /** + * @beta + * Creates an expression that extracts a specified part from a timestamp. + * + * @example + * ```typescript + * // Extract the year from the 'createdAt' timestamp. + * timestampExtract('createdAt', 'year') + * ``` + * + * @param fieldName - The name of the field representing the timestamp. + * @param part - The part to extract from the timestamp (e.g., "year", "month", "day"). + * @param timezone - The timezone to use for extraction. Valid values are from + * the TZ database (e.g., "America/Los_Angeles") or in the format "Etc/GMT-1." + * @returns A new {@code Expression} representing the extracted part as an integer. + */ + export function timestampExtract( + fieldName: string, + part: TimePart, + timezone?: string | Expression + ): FunctionExpression; + + /** + * @beta + * Creates an expression that extracts a specified part from a timestamp. + * + * @example + * ```typescript + * // Extract the part specified by the field 'part' from 'createdAt'. + * timestampExtract('createdAt', field('part')) + * ``` + * + * @param fieldName - The name of the field representing the timestamp. + * @param part - The expression evaluating to the part to extract. + * @param timezone - The timezone to use for extraction. Valid values are from + * the TZ database (e.g., "America/Los_Angeles") or in the format "Etc/GMT-1." + * @returns A new {@code Expression} representing the extracted part as an integer. + */ + export function timestampExtract( + fieldName: string, + part: Expression, + timezone?: string | Expression + ): FunctionExpression; + + /** + * @beta + * Creates an expression that extracts a specified part from a timestamp. + * + * @example + * ```typescript + * // Extract the year from the timestamp returned by the expression. + * timestampExtract(field('createdAt'), 'year') + * ``` + * + * @param timestampExpression - The expression evaluating to the timestamp. + * @param part - The part to extract from the timestamp (e.g., "year", "month", "day"). + * @param timezone - The timezone to use for extraction. Valid values are from + * the TZ database (e.g., "America/Los_Angeles") or in the format "Etc/GMT-1." + * @returns A new {@code Expression} representing the extracted part as an integer. + */ + export function timestampExtract( + timestampExpression: Expression, + part: TimePart, + timezone?: string | Expression + ): FunctionExpression; + + /** + * @beta + * Creates an expression that extracts a specified part from a timestamp. + * + * @example + * ```typescript + * // Extract the part specified by the field 'part' from the timestamp. + * timestampExtract(field('createdAt'), field('part')) + * ``` + * + * @param timestampExpression - The expression evaluating to the timestamp. + * @param part - The expression evaluating to the part to extract. + * @param timezone - The timezone to use for extraction. Valid values are from + * the TZ database (e.g., "America/Los_Angeles") or in the format "Etc/GMT-1." + * @returns A new {@code Expression} representing the extracted part as an integer. + */ + export function timestampExtract( + timestampExpression: Expression, + part: Expression, + timezone?: string | Expression + ): FunctionExpression; + /** * @beta * From 7f90d4af13b3a57813e4456f987e88cda8de2d37 Mon Sep 17 00:00:00 2001 From: Owl Bot Date: Thu, 19 Mar 2026 19:48:53 +0000 Subject: [PATCH 2/5] =?UTF-8?q?=F0=9F=A6=89=20Updates=20from=20OwlBot=20po?= =?UTF-8?q?st-processor?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md --- .../firestore/dev/src/pipelines/expression.ts | 46 +++++++++---------- .../firestore/dev/system-test/pipeline.ts | 12 ++--- handwritten/firestore/types/firestore.d.ts | 28 ++++++----- 3 files changed, 42 insertions(+), 44 deletions(-) diff --git a/handwritten/firestore/dev/src/pipelines/expression.ts b/handwritten/firestore/dev/src/pipelines/expression.ts index db4ac8a87af..02ff9472a8b 100644 --- a/handwritten/firestore/dev/src/pipelines/expression.ts +++ b/handwritten/firestore/dev/src/pipelines/expression.ts @@ -2461,7 +2461,7 @@ export abstract class Expression */ timestampDiff( start: string | Expression, - unit: 'microsecond' | 'millisecond' | 'second' | 'minute' | 'hour' | 'day' + unit: 'microsecond' | 'millisecond' | 'second' | 'minute' | 'hour' | 'day', ): FunctionExpression; timestampDiff( start: string | Expression, @@ -2472,12 +2472,13 @@ export abstract class Expression | 'minute' | 'hour' | 'day' - | Expression + | Expression, ): FunctionExpression { - return new FunctionExpression( - 'timestamp_diff', - [this, fieldOrExpression(start), valueToDefaultExpr(unit)], - ); + return new FunctionExpression('timestamp_diff', [ + this, + fieldOrExpression(start), + valueToDefaultExpr(unit), + ]); } /** @@ -2497,7 +2498,7 @@ export abstract class Expression */ timestampExtract( part: firestore.Pipelines.TimePart, - timezone?: string | Expression + timezone?: string | Expression, ): FunctionExpression; /** @@ -2517,21 +2518,18 @@ export abstract class Expression */ timestampExtract( part: Expression, - timezone?: string | Expression + timezone?: string | Expression, ): FunctionExpression; timestampExtract( part: firestore.Pipelines.TimePart | Expression, - timezone?: string | Expression + timezone?: string | Expression, ): FunctionExpression { const internalPart = isString(part) ? part.toLowerCase() : part; const args = [this, valueToDefaultExpr(internalPart)]; if (timezone) { args.push(valueToDefaultExpr(timezone)); } - return new FunctionExpression( - 'timestamp_extract', - args, - ); + return new FunctionExpression('timestamp_extract', args); } /** @@ -9667,7 +9665,7 @@ export function timestampDiff( | 'minute' | 'hour' | 'day' - | Expression + | Expression, ): FunctionExpression; /** @@ -9695,7 +9693,7 @@ export function timestampDiff( | 'minute' | 'hour' | 'day' - | Expression + | Expression, ): FunctionExpression; /** @@ -9723,7 +9721,7 @@ export function timestampDiff( | 'minute' | 'hour' | 'day' - | Expression + | Expression, ): FunctionExpression; /** @@ -9751,7 +9749,7 @@ export function timestampDiff( | 'minute' | 'hour' | 'day' - | Expression + | Expression, ): FunctionExpression; export function timestampDiff( endFieldNameOrExpression: string | Expression, @@ -9763,7 +9761,7 @@ export function timestampDiff( | 'minute' | 'hour' | 'day' - | Expression + | Expression, ): FunctionExpression { const normalizedEnd = fieldOrExpression(endFieldNameOrExpression); const normalizedStart = fieldOrExpression(startFieldNameOrExpression); @@ -9790,7 +9788,7 @@ export function timestampDiff( export function timestampExtract( fieldName: string, part: firestore.Pipelines.TimePart, - timezone?: string | Expression + timezone?: string | Expression, ): FunctionExpression; /** @@ -9812,7 +9810,7 @@ export function timestampExtract( export function timestampExtract( fieldName: string, part: Expression, - timezone?: string | Expression + timezone?: string | Expression, ): FunctionExpression; /** @@ -9834,7 +9832,7 @@ export function timestampExtract( export function timestampExtract( timestampExpression: Expression, part: firestore.Pipelines.TimePart, - timezone?: string | Expression + timezone?: string | Expression, ): FunctionExpression; /** @@ -9856,16 +9854,16 @@ export function timestampExtract( export function timestampExtract( timestampExpression: Expression, part: Expression, - timezone?: string | Expression + timezone?: string | Expression, ): FunctionExpression; export function timestampExtract( fieldNameOrExpression: string | Expression, part: firestore.Pipelines.TimePart | Expression, - timezone?: string | Expression + timezone?: string | Expression, ): FunctionExpression { return fieldOrExpression(fieldNameOrExpression).timestampExtract( valueToDefaultExpr(isString(part) ? part.toLowerCase() : part), - timezone + timezone, ); } diff --git a/handwritten/firestore/dev/system-test/pipeline.ts b/handwritten/firestore/dev/system-test/pipeline.ts index d62750cafd3..bdcd5c5a1fb 100644 --- a/handwritten/firestore/dev/system-test/pipeline.ts +++ b/handwritten/firestore/dev/system-test/pipeline.ts @@ -5090,15 +5090,9 @@ describe.skipClassic('Pipeline class', () => { ) .select( timestampDiff(field('end'), field('start'), 'hour').as('diffHour'), - field('end') - .timestampDiff(field('start'), 'minute') - .as('diffMinute'), - field('end') - .timestampDiff(field('start'), 'second') - .as('diffSecond'), - field('start') - .timestampDiff(field('end'), 'hour') - .as('diffHourNeg'), + field('end').timestampDiff(field('start'), 'minute').as('diffMinute'), + field('end').timestampDiff(field('start'), 'second').as('diffSecond'), + field('start').timestampDiff(field('end'), 'hour').as('diffHourNeg'), ) .execute(); diff --git a/handwritten/firestore/types/firestore.d.ts b/handwritten/firestore/types/firestore.d.ts index dbbca3bf714..f70f90347e8 100644 --- a/handwritten/firestore/types/firestore.d.ts +++ b/handwritten/firestore/types/firestore.d.ts @@ -5604,7 +5604,13 @@ declare namespace FirebaseFirestore { */ timestampDiff( start: string | Expression, - unit: 'microsecond' | 'millisecond' | 'second' | 'minute' | 'hour' | 'day' + unit: + | 'microsecond' + | 'millisecond' + | 'second' + | 'minute' + | 'hour' + | 'day', ): FunctionExpression; /** @@ -5624,7 +5630,7 @@ declare namespace FirebaseFirestore { */ timestampExtract( part: TimePart, - timezone?: string | Expression + timezone?: string | Expression, ): FunctionExpression; /** @@ -5644,7 +5650,7 @@ declare namespace FirebaseFirestore { */ timestampExtract( part: Expression, - timezone?: string | Expression + timezone?: string | Expression, ): FunctionExpression; /** @@ -11440,7 +11446,7 @@ declare namespace FirebaseFirestore { | 'minute' | 'hour' | 'day' - | Expression + | Expression, ): FunctionExpression; /** @@ -11468,7 +11474,7 @@ declare namespace FirebaseFirestore { | 'minute' | 'hour' | 'day' - | Expression + | Expression, ): FunctionExpression; /** @@ -11496,7 +11502,7 @@ declare namespace FirebaseFirestore { | 'minute' | 'hour' | 'day' - | Expression + | Expression, ): FunctionExpression; /** @@ -11524,7 +11530,7 @@ declare namespace FirebaseFirestore { | 'minute' | 'hour' | 'day' - | Expression + | Expression, ): FunctionExpression; /** @@ -11546,7 +11552,7 @@ declare namespace FirebaseFirestore { export function timestampExtract( fieldName: string, part: TimePart, - timezone?: string | Expression + timezone?: string | Expression, ): FunctionExpression; /** @@ -11568,7 +11574,7 @@ declare namespace FirebaseFirestore { export function timestampExtract( fieldName: string, part: Expression, - timezone?: string | Expression + timezone?: string | Expression, ): FunctionExpression; /** @@ -11590,7 +11596,7 @@ declare namespace FirebaseFirestore { export function timestampExtract( timestampExpression: Expression, part: TimePart, - timezone?: string | Expression + timezone?: string | Expression, ): FunctionExpression; /** @@ -11612,7 +11618,7 @@ declare namespace FirebaseFirestore { export function timestampExtract( timestampExpression: Expression, part: Expression, - timezone?: string | Expression + timezone?: string | Expression, ): FunctionExpression; /** From 0fea83f059ab622400e6c27112620a643051281c Mon Sep 17 00:00:00 2001 From: Owl Bot Date: Thu, 19 Mar 2026 19:51:02 +0000 Subject: [PATCH 3/5] =?UTF-8?q?=F0=9F=A6=89=20Updates=20from=20OwlBot=20po?= =?UTF-8?q?st-processor?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md --- .../firestore/dev/src/pipelines/expression.ts | 46 +++++++++---------- .../firestore/dev/system-test/pipeline.ts | 12 ++--- handwritten/firestore/types/firestore.d.ts | 28 ++++++----- 3 files changed, 42 insertions(+), 44 deletions(-) diff --git a/handwritten/firestore/dev/src/pipelines/expression.ts b/handwritten/firestore/dev/src/pipelines/expression.ts index db4ac8a87af..02ff9472a8b 100644 --- a/handwritten/firestore/dev/src/pipelines/expression.ts +++ b/handwritten/firestore/dev/src/pipelines/expression.ts @@ -2461,7 +2461,7 @@ export abstract class Expression */ timestampDiff( start: string | Expression, - unit: 'microsecond' | 'millisecond' | 'second' | 'minute' | 'hour' | 'day' + unit: 'microsecond' | 'millisecond' | 'second' | 'minute' | 'hour' | 'day', ): FunctionExpression; timestampDiff( start: string | Expression, @@ -2472,12 +2472,13 @@ export abstract class Expression | 'minute' | 'hour' | 'day' - | Expression + | Expression, ): FunctionExpression { - return new FunctionExpression( - 'timestamp_diff', - [this, fieldOrExpression(start), valueToDefaultExpr(unit)], - ); + return new FunctionExpression('timestamp_diff', [ + this, + fieldOrExpression(start), + valueToDefaultExpr(unit), + ]); } /** @@ -2497,7 +2498,7 @@ export abstract class Expression */ timestampExtract( part: firestore.Pipelines.TimePart, - timezone?: string | Expression + timezone?: string | Expression, ): FunctionExpression; /** @@ -2517,21 +2518,18 @@ export abstract class Expression */ timestampExtract( part: Expression, - timezone?: string | Expression + timezone?: string | Expression, ): FunctionExpression; timestampExtract( part: firestore.Pipelines.TimePart | Expression, - timezone?: string | Expression + timezone?: string | Expression, ): FunctionExpression { const internalPart = isString(part) ? part.toLowerCase() : part; const args = [this, valueToDefaultExpr(internalPart)]; if (timezone) { args.push(valueToDefaultExpr(timezone)); } - return new FunctionExpression( - 'timestamp_extract', - args, - ); + return new FunctionExpression('timestamp_extract', args); } /** @@ -9667,7 +9665,7 @@ export function timestampDiff( | 'minute' | 'hour' | 'day' - | Expression + | Expression, ): FunctionExpression; /** @@ -9695,7 +9693,7 @@ export function timestampDiff( | 'minute' | 'hour' | 'day' - | Expression + | Expression, ): FunctionExpression; /** @@ -9723,7 +9721,7 @@ export function timestampDiff( | 'minute' | 'hour' | 'day' - | Expression + | Expression, ): FunctionExpression; /** @@ -9751,7 +9749,7 @@ export function timestampDiff( | 'minute' | 'hour' | 'day' - | Expression + | Expression, ): FunctionExpression; export function timestampDiff( endFieldNameOrExpression: string | Expression, @@ -9763,7 +9761,7 @@ export function timestampDiff( | 'minute' | 'hour' | 'day' - | Expression + | Expression, ): FunctionExpression { const normalizedEnd = fieldOrExpression(endFieldNameOrExpression); const normalizedStart = fieldOrExpression(startFieldNameOrExpression); @@ -9790,7 +9788,7 @@ export function timestampDiff( export function timestampExtract( fieldName: string, part: firestore.Pipelines.TimePart, - timezone?: string | Expression + timezone?: string | Expression, ): FunctionExpression; /** @@ -9812,7 +9810,7 @@ export function timestampExtract( export function timestampExtract( fieldName: string, part: Expression, - timezone?: string | Expression + timezone?: string | Expression, ): FunctionExpression; /** @@ -9834,7 +9832,7 @@ export function timestampExtract( export function timestampExtract( timestampExpression: Expression, part: firestore.Pipelines.TimePart, - timezone?: string | Expression + timezone?: string | Expression, ): FunctionExpression; /** @@ -9856,16 +9854,16 @@ export function timestampExtract( export function timestampExtract( timestampExpression: Expression, part: Expression, - timezone?: string | Expression + timezone?: string | Expression, ): FunctionExpression; export function timestampExtract( fieldNameOrExpression: string | Expression, part: firestore.Pipelines.TimePart | Expression, - timezone?: string | Expression + timezone?: string | Expression, ): FunctionExpression { return fieldOrExpression(fieldNameOrExpression).timestampExtract( valueToDefaultExpr(isString(part) ? part.toLowerCase() : part), - timezone + timezone, ); } diff --git a/handwritten/firestore/dev/system-test/pipeline.ts b/handwritten/firestore/dev/system-test/pipeline.ts index d62750cafd3..bdcd5c5a1fb 100644 --- a/handwritten/firestore/dev/system-test/pipeline.ts +++ b/handwritten/firestore/dev/system-test/pipeline.ts @@ -5090,15 +5090,9 @@ describe.skipClassic('Pipeline class', () => { ) .select( timestampDiff(field('end'), field('start'), 'hour').as('diffHour'), - field('end') - .timestampDiff(field('start'), 'minute') - .as('diffMinute'), - field('end') - .timestampDiff(field('start'), 'second') - .as('diffSecond'), - field('start') - .timestampDiff(field('end'), 'hour') - .as('diffHourNeg'), + field('end').timestampDiff(field('start'), 'minute').as('diffMinute'), + field('end').timestampDiff(field('start'), 'second').as('diffSecond'), + field('start').timestampDiff(field('end'), 'hour').as('diffHourNeg'), ) .execute(); diff --git a/handwritten/firestore/types/firestore.d.ts b/handwritten/firestore/types/firestore.d.ts index dbbca3bf714..f70f90347e8 100644 --- a/handwritten/firestore/types/firestore.d.ts +++ b/handwritten/firestore/types/firestore.d.ts @@ -5604,7 +5604,13 @@ declare namespace FirebaseFirestore { */ timestampDiff( start: string | Expression, - unit: 'microsecond' | 'millisecond' | 'second' | 'minute' | 'hour' | 'day' + unit: + | 'microsecond' + | 'millisecond' + | 'second' + | 'minute' + | 'hour' + | 'day', ): FunctionExpression; /** @@ -5624,7 +5630,7 @@ declare namespace FirebaseFirestore { */ timestampExtract( part: TimePart, - timezone?: string | Expression + timezone?: string | Expression, ): FunctionExpression; /** @@ -5644,7 +5650,7 @@ declare namespace FirebaseFirestore { */ timestampExtract( part: Expression, - timezone?: string | Expression + timezone?: string | Expression, ): FunctionExpression; /** @@ -11440,7 +11446,7 @@ declare namespace FirebaseFirestore { | 'minute' | 'hour' | 'day' - | Expression + | Expression, ): FunctionExpression; /** @@ -11468,7 +11474,7 @@ declare namespace FirebaseFirestore { | 'minute' | 'hour' | 'day' - | Expression + | Expression, ): FunctionExpression; /** @@ -11496,7 +11502,7 @@ declare namespace FirebaseFirestore { | 'minute' | 'hour' | 'day' - | Expression + | Expression, ): FunctionExpression; /** @@ -11524,7 +11530,7 @@ declare namespace FirebaseFirestore { | 'minute' | 'hour' | 'day' - | Expression + | Expression, ): FunctionExpression; /** @@ -11546,7 +11552,7 @@ declare namespace FirebaseFirestore { export function timestampExtract( fieldName: string, part: TimePart, - timezone?: string | Expression + timezone?: string | Expression, ): FunctionExpression; /** @@ -11568,7 +11574,7 @@ declare namespace FirebaseFirestore { export function timestampExtract( fieldName: string, part: Expression, - timezone?: string | Expression + timezone?: string | Expression, ): FunctionExpression; /** @@ -11590,7 +11596,7 @@ declare namespace FirebaseFirestore { export function timestampExtract( timestampExpression: Expression, part: TimePart, - timezone?: string | Expression + timezone?: string | Expression, ): FunctionExpression; /** @@ -11612,7 +11618,7 @@ declare namespace FirebaseFirestore { export function timestampExtract( timestampExpression: Expression, part: Expression, - timezone?: string | Expression + timezone?: string | Expression, ): FunctionExpression; /** From a34eab96f02dd78af248fb359a39234be499e91f Mon Sep 17 00:00:00 2001 From: Yvonne Pan <103622026+yvonnep165@users.noreply.github.com> Date: Thu, 19 Mar 2026 15:51:16 -0400 Subject: [PATCH 4/5] Add documentation for timestamp timezone missing --- handwritten/firestore/dev/src/pipelines/expression.ts | 6 ++++++ handwritten/firestore/types/firestore.d.ts | 6 ++++++ 2 files changed, 12 insertions(+) diff --git a/handwritten/firestore/dev/src/pipelines/expression.ts b/handwritten/firestore/dev/src/pipelines/expression.ts index 02ff9472a8b..860a355d37a 100644 --- a/handwritten/firestore/dev/src/pipelines/expression.ts +++ b/handwritten/firestore/dev/src/pipelines/expression.ts @@ -2494,6 +2494,7 @@ export abstract class Expression * @param part - The part to extract from the timestamp (e.g., "year", "month", "day"). * @param timezone - The timezone to use for extraction. Valid values are from * the TZ database (e.g., "America/Los_Angeles") or in the format "Etc/GMT-1." + * Defaults to "UTC" if not specified. * @returns A new `Expression` representing the extracted part as an integer. */ timestampExtract( @@ -2514,6 +2515,7 @@ export abstract class Expression * @param part - The expression evaluating to the part to extract. * @param timezone - The timezone to use for extraction. Valid values are from * the TZ database (e.g., "America/Los_Angeles") or in the format "Etc/GMT-1." + * Defaults to "UTC" if not specified. * @returns A new `Expression` representing the extracted part as an integer. */ timestampExtract( @@ -9783,6 +9785,7 @@ export function timestampDiff( * @param part - The part to extract from the timestamp (e.g., "year", "month", "day"). * @param timezone - The timezone to use for extraction. Valid values are from * the TZ database (e.g., "America/Los_Angeles") or in the format "Etc/GMT-1." + * Defaults to "UTC" if not specified. * @returns A new `Expression` representing the extracted part as an integer. */ export function timestampExtract( @@ -9805,6 +9808,7 @@ export function timestampExtract( * @param part - The expression evaluating to the part to extract. * @param timezone - The timezone to use for extraction. Valid values are from * the TZ database (e.g., "America/Los_Angeles") or in the format "Etc/GMT-1." + * Defaults to "UTC" if not specified. * @returns A new `Expression` representing the extracted part as an integer. */ export function timestampExtract( @@ -9827,6 +9831,7 @@ export function timestampExtract( * @param part - The part to extract from the timestamp (e.g., "year", "month", "day"). * @param timezone - The timezone to use for extraction. Valid values are from * the TZ database (e.g., "America/Los_Angeles") or in the format "Etc/GMT-1." + * Defaults to "UTC" if not specified. * @returns A new `Expression` representing the extracted part as an integer. */ export function timestampExtract( @@ -9849,6 +9854,7 @@ export function timestampExtract( * @param part - The expression evaluating to the part to extract. * @param timezone - The timezone to use for extraction. Valid values are from * the TZ database (e.g., "America/Los_Angeles") or in the format "Etc/GMT-1." + * Defaults to "UTC" if not specified. * @returns A new `Expression` representing the extracted part as an integer. */ export function timestampExtract( diff --git a/handwritten/firestore/types/firestore.d.ts b/handwritten/firestore/types/firestore.d.ts index f70f90347e8..dd5f8c3f9ce 100644 --- a/handwritten/firestore/types/firestore.d.ts +++ b/handwritten/firestore/types/firestore.d.ts @@ -5626,6 +5626,7 @@ declare namespace FirebaseFirestore { * @param part - The part to extract from the timestamp (e.g., "year", "month", "day"). * @param timezone - The timezone to use for extraction. Valid values are from * the TZ database (e.g., "America/Los_Angeles") or in the format "Etc/GMT-1." + * Defaults to "UTC" if not specified. * @returns A new `Expression` representing the extracted part as an integer. */ timestampExtract( @@ -5646,6 +5647,7 @@ declare namespace FirebaseFirestore { * @param part - The expression evaluating to the part to extract. * @param timezone - The timezone to use for extraction. Valid values are from * the TZ database (e.g., "America/Los_Angeles") or in the format "Etc/GMT-1." + * Defaults to "UTC" if not specified. * @returns A new `Expression` representing the extracted part as an integer. */ timestampExtract( @@ -11547,6 +11549,7 @@ declare namespace FirebaseFirestore { * @param part - The part to extract from the timestamp (e.g., "year", "month", "day"). * @param timezone - The timezone to use for extraction. Valid values are from * the TZ database (e.g., "America/Los_Angeles") or in the format "Etc/GMT-1." + * Defaults to "UTC" if not specified. * @returns A new {@code Expression} representing the extracted part as an integer. */ export function timestampExtract( @@ -11569,6 +11572,7 @@ declare namespace FirebaseFirestore { * @param part - The expression evaluating to the part to extract. * @param timezone - The timezone to use for extraction. Valid values are from * the TZ database (e.g., "America/Los_Angeles") or in the format "Etc/GMT-1." + * Defaults to "UTC" if not specified. * @returns A new {@code Expression} representing the extracted part as an integer. */ export function timestampExtract( @@ -11591,6 +11595,7 @@ declare namespace FirebaseFirestore { * @param part - The part to extract from the timestamp (e.g., "year", "month", "day"). * @param timezone - The timezone to use for extraction. Valid values are from * the TZ database (e.g., "America/Los_Angeles") or in the format "Etc/GMT-1." + * Defaults to "UTC" if not specified. * @returns A new {@code Expression} representing the extracted part as an integer. */ export function timestampExtract( @@ -11613,6 +11618,7 @@ declare namespace FirebaseFirestore { * @param part - The expression evaluating to the part to extract. * @param timezone - The timezone to use for extraction. Valid values are from * the TZ database (e.g., "America/Los_Angeles") or in the format "Etc/GMT-1." + * Defaults to "UTC" if not specified. * @returns A new {@code Expression} representing the extracted part as an integer. */ export function timestampExtract( From 46c7eb04c89cfceac1dfd6f7a28716cfd7483cfb Mon Sep 17 00:00:00 2001 From: Yvonne Pan <103622026+yvonnep165@users.noreply.github.com> Date: Thu, 26 Mar 2026 15:48:06 -0400 Subject: [PATCH 5/5] Change the start parameter description --- handwritten/firestore/dev/src/pipelines/expression.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/handwritten/firestore/dev/src/pipelines/expression.ts b/handwritten/firestore/dev/src/pipelines/expression.ts index a295f604045..fad626b789d 100644 --- a/handwritten/firestore/dev/src/pipelines/expression.ts +++ b/handwritten/firestore/dev/src/pipelines/expression.ts @@ -2422,7 +2422,7 @@ export abstract class Expression * field("endTime").timestampDiff("startTime", "day"); * ``` * - * @param start - The field name of the starting timestamp. + * @param start - The field name of the starting timestamp or an expression evaluating to a timestamp. * @param unit - The unit of time for the difference (e.g., "day", "hour"). * @returns A new `Expression` representing the difference as an integer. */