timestampExtract

Firestore pipelines timestampExtract() expression helper: pull a calendar part (year, month, day) out of a timestamp.

Prerequisites

  • @react-native-firebase/app installed and native config completed per Getting Started.
  • @react-native-firebase/firestore installed and rebuilt into the native app.
  • A Firestore Enterprise database. See Pipelines overview.
  • Import expression helpers from @react-native-firebase/firestore/pipelines.

timestampExtract() reads a calendar component (such as year, month, or day) from a timestamp. An optional third argument is a timezone, given as a string or as an expression that evaluates to one. Firestore uses it to pick the calendar for extraction, so the value you pass must be a timezone name the Firestore backend accepts.

Valid part values are the TimePart literals: 'microsecond', 'millisecond', 'second', 'minute', 'hour', 'day', 'week', 'week(monday)' through 'week(sunday)', 'isoweek', 'month', 'quarter', 'year', 'isoyear', 'dayofweek', and 'dayofyear'.

Basic example

js
import { getFirestore } from '@react-native-firebase/firestore';
import { execute, field, timestampExtract } from '@react-native-firebase/firestore/pipelines';

const db = getFirestore('your-enterprise-database-id');

const snapshot = await execute(
  db
    .pipeline()
    .collection('events')
    .select(
      timestampExtract(field('createdAt'), 'year').as('createdYear'),
      timestampExtract('createdAt', 'month').as('createdMonth'),
      timestampExtract(field('createdAt'), 'day').as('createdDay'),
    ),
);

snapshot.results.forEach(row => {
  console.log(row.data().createdYear, row.data().createdMonth, row.data().createdDay);
});

With a timezone

js
import { getFirestore } from '@react-native-firebase/firestore';
import { execute, field, timestampExtract } from '@react-native-firebase/firestore/pipelines';

const db = getFirestore('your-enterprise-database-id');

const snapshot = await execute(
  db
    .pipeline()
    .collection('events')
    .select(
      timestampExtract(field('createdAt'), 'hour', 'America/Los_Angeles').as('localHour'),
      timestampExtract('createdAt', 'dayofweek').as('weekday'),
    ),
);

snapshot.results.forEach(row => {
  console.log(row.data().localHour, row.data().weekday);
});

Related helpers

{/* prettier-ignore */}

HelperUse when
timestampExtractRead year, month, day, or other calendar part
timestampTruncateBucket timestamps to a granularity
timestampDiffMeasure elapsed time between timestamps
TimePartType for part literals such as 'year'

Upstream reference

See the firebase-js-sdk timestampExtract declaration for full overload signatures and supported TimePart values.

On this page