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.
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.
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.
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.
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.
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.
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.
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.
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 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.
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.