Configurations

Most settings affect how a writer groups and buffers data. A reader does not need the original Page-size target or flush threshold: the resulting boundaries are recorded in the file. A few settings, including timestamp units and non-aligned time encoding, still need to be agreed by the applications exchanging the file.

The table distinguishes those cases. Setting names in language-specific APIs may differ.

Conceptual setting	Observable file effect	Setting serialized directly?	Reader needs original setting?
Chunk Group size	Where a device group is flushed	No	No
Page size target	Page boundaries and Statistics granularity	No	No
Maximum points per Page	Page boundaries	No	No
Metadata index fanout	Index-tree depth and node widths	No	No
Bloom false-positive rate	Generated bit count and hash-function count	No; generated values are serialized	No
Value encoding	Encoded Page stream	Yes, as encoding_type in each Chunk	No
Compression	Stored Page payload	Yes, as compression_type in each Chunk	No
Time precision and zone	Interpretation of int64 timestamps	No	Yes, from the surrounding protocol
Non-aligned time encoding	Encoded time stream in each non-aligned Page	No	Yes
Encryption	File encryption header, Chunk authentication, Page bodies, or legacy footer properties	Provider/profile or legacy properties are serialized; key context is external	Yes, when encrypted

For example, a Page-size target is not stored as a setting, but each Page records its actual size.

Chunk Group Size

The Chunk Group size is the amount of data that a writer buffers before it flushes the Chunks of the current device. Larger Chunk Groups reduce marker and metadata overhead and favor sequential I/O, but require more writer memory. Smaller Chunk Groups reduce peak memory and make data available to the output sooner.

The configured size is a flush threshold, not an exact on-disk size. The format does not prescribe a default. A group begins with a 0x00 Chunk Group Header and ends at the next group, operation-index record, or separator. Individual Chunk markers continue the current group.

Data Page Size

The Data Page size is a target for the in-memory data accumulated by a series writer. Smaller Pages provide finer-grained Statistics and skipping. Larger Pages reduce Page Header overhead and can improve compression, at the cost of more buffering and coarser skipping.

The threshold is not an exact serialized Page size. A writer can finish a Page earlier because of the maximum point count, an explicit flush, or aligned-page boundary requirements. The actual Page boundary is determined by the Page Header lengths. The format does not prescribe a default Page size.

Maximum Points per Page

A writer may limit the number of logical positions in one Page independently of the Page size target. This prevents a Page containing many compact values from growing to an excessive number of points. A common writer setting is 10,000 points.

For aligned series, the Time Page and its corresponding Value Pages must cover the same logical position range. A writer therefore applies a common boundary to the aligned columns.

The configured limit is not stored as a separate field. Readers use Page boundaries and, for an aligned Value Page, position_count.

Metadata Index Fanout

Index fanout is the maximum number of children in an internal metadata index node. A larger fanout produces a shallower tree with larger nodes; a smaller fanout produces a deeper tree with smaller nodes. The value should be at least 2; a common value is 256.

The configured limit is not serialized. Each metadata index node stores its node type, children, and end offset, so a reader traverses the resulting tree without knowing the writer setting.

Bloom Filter False-positive Rate

A Bloom filter can report “possibly present” for a path that is absent. Lowering the target false-positive rate reduces those extra lookups at the cost of more bits and hash functions. Standard writers constrain the value to the range 0.01 through 0.10 and use 0.05 by default.

The rate itself is not serialized. The resulting filter bytes, bit count, and hash-function count are stored in TsFileMetadata, so a reader does not need the writer setting. See Bloom Filter.

Value Encoding and Compression

A writer may select a default value encoding by physical type and a default compression method. These defaults are schema and writer policies rather than shared reader configuration:

• encoding_type in the Chunk Header identifies the value encoding, or the time encoding for an aligned Time Chunk.
• compression_type in the Chunk Header identifies how every Page in the Chunk is compressed.

Consequently, a reader uses the Chunk Header and does not need the writer's defaults. Supported identifiers and their payload formats are defined in Encodings and Compression.

Time Precision and Time Zone

A physical timestamp is a signed 64-bit integer. TsFile v4 does not record a time unit or time zone in the file. The protocol that uses the file defines whether the precision is milliseconds, microseconds, nanoseconds, or another unit, as well as any time-zone semantics.

Non-aligned Time Encoding

The encoding_type in a non-aligned Chunk Header describes the value stream, not the time stream in the same Page. Readers and writers determine the non-aligned time-stream encoding from shared configuration. The default is TS_2DIFF.

This restriction does not apply to an aligned Time Chunk. Its Chunk Header records the time encoding in encoding_type.

Encryption

Encryption uses one of two descriptions: the optional file encryption header for Page AEAD, or footer properties for legacy encryption. Both record how to interpret the Page bytes, while key access remains external. The AEAD header is authoritative even though its legacy footer properties say unencrypted. The layouts and mode-selection rules are in Encryption.

Implementation Settings

Settings for memory allocation, memory-check cadence, batch size, parallel execution, thread count, storage backend, and close-time synchronization do not define TsFile bytes. They are implementation and deployment concerns and are outside this file-format specification.