Unclear or non-working where function for query with date field

[pandabrand]

I'm trying to build a filter mechanism. I have this function:

    const filter = (filters: IFilter[]) => {
        const queries: any[] = []

        filters.forEach((field) => {
            queries.push(
                stack
                .contentType(contentType)
                .entry()
                .query()
                .where(field.uid, QueryOperation.INCLUDES, field.params)
            )
        })

        query.queryOperator(QueryOperator.OR, ...queries)

        query
        .includeCount()
        .paginate({skip: 0, limit: perPage})
        .orderByDescending(sortField)
        .find()
        .then((res) => {
            dispatch({
                type: 'ADD_ENTRIES',
                payload: {
                    entries: res.entries ?? [],
                    count: res.count ?? 0
                }
            })
        })
    }

I can't find any documentation whether the date field is stored as a string or a number. In the example I'm testing the field.params is carrying an array of years as a string. I have also tried converting to an int. I always get an empty result. Since I can't find any documentation to verify whether or not this is correct, I'm also reaching out in case this is an issue.

[sunil-lakshman]

@pandabrand Thanks for the detailed example. 🙌

How dates are represented
In the Content Delivery API, Date fields are returned and queried as ISO-8601 strings (for example, "2026-04-09T07:45:23.000Z"). They are not stored as a bare year and not as a numeric timestamp.

Why QueryOperation.INCLUDES with years returns no rows
INCLUDES maps to the $in operator, which only matches when the field value exactly equals one of the values in the array.
So if an entry has "date": "2026-04-09T07:45:23.000Z", passing ["2025", "2026"] will not match. This is expected behavior and not an SDK issue.

Recommended approach — use ISO date ranges

Example using the TypeScript Delivery SDK:

`import contentstack, { QueryOperator } from '@contentstack/delivery-sdk';

const stack = contentstack.stack({
  apiKey: 'YOUR_API_KEY',
  deliveryToken: 'YOUR_DELIVERY_TOKEN',
  environment: 'YOUR_ENVIRONMENT',
});

// One year: date field must fall inside this ISO range
const res = await stack
  .contentType('ct1')
  .entry()
  .query({
    date: {
      $gte: '2026-01-01T00:00:00.000Z',
      $lte: '2026-12-31T23:59:59.999Z',
    },
  })
  .find();`

Multiple years — combine ranges using OR

`const y2025 = stack.contentType('ct1').entry().query({
  date: {
    $gte: '2025-01-01T00:00:00.000Z',
    $lte: '2025-12-31T23:59:59.999Z',
  },
});

const y2026 = stack.contentType('ct1').entry().query({
  date: {
    $gte: '2026-01-01T00:00:00.000Z',
    $lte: '2026-12-31T23:59:59.999Z',
  },
});

const resOr = await stack
  .contentType('ct1')
  .entry()
  .query()
  .queryOperator(QueryOperator.OR, y2025, y2026)
  .find();`

Alternatively, if you frequently need to filter by year, you may consider storing a separate year field (string or number) and using $in directly.