nczarr_chunking.c File Reference

Demonstrate chunked storage in a local NcZarr dataset. More...

#include <netcdf.h>
#include <stdio.h>
#include <stdlib.h>

Macros
#define	FILE_URL   "file://nczarr_chunking.zarr#mode=nczarr"
#define	NY   4
#define	NX   5
#define	NDIMS   2
#define	CHUNK_Y   2
#define	CHUNK_X   5
#define	ERR(e)

Functions
int	main (void)

Detailed Description

Demonstrate chunked storage in a local NcZarr dataset.

This example extends nczarr_simple.c by adding explicit chunk shape selection. Chunking controls how a variable's data is split into separate storage units (chunks) in the underlying Zarr directory tree. Each chunk becomes a separate file on disk (or object in cloud storage), so the chunk shape directly affects I/O access patterns.

The program creates the same 4x5 temperature grid used in nczarr_simple.c but specifies a 2x5 (y x x) chunk shape using nc_def_var_chunking(). This splits the 4-row array into two 2-row chunks. After writing, the program reopens the dataset and verifies the chunk metadata via nc_inq_var_chunking(), then reads and validates all data values.

Learning Objectives:

• Set explicit chunk shape for a variable in a NcZarr dataset
• Query chunk metadata (storage type and chunk dimensions) after reopen
• Understand that the same nc_def_var_chunking() / nc_inq_var_chunking() APIs used for NetCDF-4/HDF5 work identically with NcZarr
• Observe that each chunk maps to a separate file in the Zarr store

Key Concepts:

• NC_CHUNKED: Storage mode that splits data into fixed-size chunks
• nc_def_var_chunking(): Sets the chunk shape (must be called in define mode, before nc_enddef)
• nc_inq_var_chunking(): Returns storage type and chunk dimensions
• Chunk alignment: Best practice is to choose chunk dimensions that evenly divide the variable dimensions

Related Examples:

• nczarr_simple.c - Basic NcZarr create/read/write (default chunking)
• nczarr_compression.c - Adding compression on top of chunking
• chunking_performance.c - Comparing access patterns with different chunk shapes (performance example)

Compilation:

gcc -o nczarr_chunking nczarr_chunking.c -lnetcdf

Usage:

./nczarr_chunking
ncdump 'file://nczarr_chunking.zarr#mode=nczarr'

Expected Output: Creates the directory nczarr_chunking.zarr containing:

• 2 dimensions: y(4), x(5)
• 1 variable: temperature(y, x) of type NC_FLOAT with chunks [2, 5]
• Attributes: units="K", long_name="Temperature", _FillValue=-999.f
• A 4x5 temperature data grid stored in 2 chunks of 2x5 each

Note

Companion code for "The NetCDF Developer's Handbook: The Authoritative Guide to Writing High-Performance Programs for Scientific Data Management, Second Edition" (https://www.amazon.com/dp/B0H7Q1Z75L)

Author

Edward Hartnett, Intelligent Data Design, Inc.

Date

2026-06-26

Macro Definition Documentation

CHUNK_X

#define CHUNK_X   5

CHUNK_Y

#define CHUNK_Y   2

ERR

#define ERR

(

e

)

Value:

    do { \
    if (e) { \
        fprintf(stderr, "Error: %s at line %d\n", nc_strerror(e), __LINE__); \
        return 1; \
    } \
} while(0)

FILE_URL

#define FILE_URL   "file://nczarr_chunking.zarr#mode=nczarr"

NDIMS

#define NDIMS   2

NX

#define NX   5

NY

#define NY   4

Function Documentation

main()

int main

(

void

)