Implementation:Apache Druid SampleForTimestamp

Knowledge Sources	Apache Druid Druid Timestamp Spec
Domains	Data_Ingestion, Time_Series
Last Updated	2026-02-10 00:00 GMT

Overview

Concrete sampler API client function for previewing timestamp extraction from parsed data columns.

Description

The sampleForTimestamp function performs a two-phase sampling operation. First, it queries with a static placeholder timestamp to get all columns. Then, if in column mode, it queries again with the user's timestampSpec to extract the __time column. The two responses are merged so the user sees both the original columns and the parsed timestamp side by side.

This dual-query approach ensures that timestamp parsing errors don't hide the column data, enabling users to diagnose format mismatches.

Usage

Call this function after data parsing when the user has selected a timestamp column and format. The function validates that the timestamp extraction produces valid time values.

Code Reference

Source Location

Repository: Apache Druid
File: web-console/src/utils/sampler.ts
Lines: L386-L466

Signature

export async function sampleForTimestamp(
  spec: Partial<IngestionSpec>,
  cacheRows: CacheRows,
): Promise<SampleResponse>

Import

import { sampleForTimestamp } from '../utils/sampler';

I/O Contract

Inputs

Name	Type	Required	Description
spec	Partial<IngestionSpec>	Yes	Ingestion spec with timestampSpec configured (column, format)
cacheRows	CacheRows	Yes	Cached parsed data from previous sampler calls

Outputs

Name	Type	Description
data	SampleEntry[]	Array of rows with both original columns and __time column populated
cacheKey	string or undefined	Cache key for subsequent calls

Usage Examples

ISO 8601 Timestamp

import { sampleForTimestamp } from '../utils/sampler';

const spec = {
  type: 'index_parallel',
  spec: {
    dataSchema: {
      timestampSpec: {
        column: 'event_time',
        format: 'iso',
      },
    },
    ioConfig: { /* ... */ },
  },
};

const result = await sampleForTimestamp(spec, cachedRows);
// result.data[0].parsed.__time = '2024-01-01T00:00:00.000Z'

Epoch Milliseconds

const epochSpec = {
  type: 'index_parallel',
  spec: {
    dataSchema: {
      timestampSpec: {
        column: 'ts',
        format: 'millis',
      },
    },
    ioConfig: { /* ... */ },
  },
};

const result = await sampleForTimestamp(epochSpec, cachedRows);

Related Pages

Implements Principle

Principle:Apache_Druid_Timestamp_Configuration

Requires Environment

Uses Heuristic

Heuristic:Apache_Druid_Sampler_Limitations_And_Workarounds

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment