Data Types

Every SPQL function signature names the data types of its parameters and its result. This page uses the same type names as the signatures. Primitive types hold scalar values. Nested types combine other types into structs and lists. Semantic types attach a meaning, such as an image, a tensor, or a timestamp, to a storage layout.

A ? after a type name means that the value can be null. For example, i64? is a nullable 64-bit signed integer.

Primitive TypesCopy Anchor Link

Nested TypesCopy Anchor Link

Combine any types into structs and lists, nested to any depth. Each struct field and each list element has its own nullability.

Semantic TypesCopy Anchor Link

A semantic type gives a stable meaning to a storage layout. The Type ID identifies the semantic type in schemas and function signatures. Two types with the same storage layout and different Type IDs do not match: a vector is not an arbitrary fixed-size list. Parameters, such as a vector dimension or a time unit, refine the type.

Type parameter tables describe values shared by a column. A trailing ? in a parameter kind means that parameter can be absent.

The time_unit kind uses s, ms, us, ns or d. The period_frequency kind uses D, W, MS, ME, QS, QE, YS or YE.

Types defined by Spiral list their stability. A stable type keeps its Type ID and storage from one release to the next, so files you write today stay readable. An experimental type can still change. A deprecated type names the type that replaces it.

An alias is an earlier Type ID that Spiral still reads. Spiral always writes the Type ID, so a column read under an alias is written back under its current Type ID. When a type exports to Arrow under an extension name that differs from its Type ID, the type lists that name.

Type IDs that start with vortex. belong to the Vortex file format, an open columnar format, so any Vortex reader recognizes them without Spiral. Visualization components in the spql.viz namespace are presentation values, not data types; the visualization components page documents them.

The semantic types on this page, with their storage, stability, and aliases, are also published as one JSON file, spql-types.v1.json, described by the JSON Schema spql-types.v1.schema.json. Each Rust SDK release attaches both files, so code generators and validators can read the types of the release they build against.

Date and TimeCopy Anchor Link

spql.DurationCopy Anchor Link

Fixed elapsed time in the parameter's unit.

• Stability: stable
• Storage: i64
• Aliases: spql.dt.Duration

Type parameters

spql.IntervalCopy Anchor Link

Calendar-relative SQL interval.

• Stability: stable
• Storage: struct { months, days, nanos }
• Aliases: spql.dt.Interval

Fields

spql.PeriodCopy Anchor Link

Regular period label at the parameter's frequency.

• Stability: stable
• Storage: i64
• Aliases: spql.dt.Period

Type parameters

vortex.dateCopy Anchor Link

Calendar dates counted from the Unix epoch, in days (days) or milliseconds (ms).

• Defined by: the Vortex file format
• Storage: i32 for days; i64 for milliseconds.
• Arrow: exports as the native Arrow type

Type parameters

vortex.timeCopy Anchor Link

Time of day counted from midnight, in seconds (s), milliseconds (ms), microseconds (us) or nanoseconds (ns).

• Defined by: the Vortex file format
• Storage: i32 for seconds or milliseconds; i64 for microseconds or nanoseconds.
• Arrow: exports as the native Arrow type

Type parameters

vortex.timestampCopy Anchor Link

Timestamps counted from the Unix epoch in seconds (s), milliseconds (ms), microseconds (us) or nanoseconds (ns), with an optional IANA timezone name or fixed offset. The timezone describes calendar interpretation without changing the stored instant.

• Defined by: the Vortex file format
• Storage: i64 in the selected unit.
• Arrow: exports as the native Arrow type

Type parameters

BlobsCopy Anchor Link

spql.BlobCopy Anchor Link

Inline bytes, a Spiral address or a direct provider URI, exposed as spql.Blob.

• Stability: stable
• Storage: struct { bytes, uri, offset, size, mime_type, version, etag, digest }
• Aliases: spql.io.Blob

Fields

MediaCopy Anchor Link

spql.ClipRefCopy Anchor Link

A half-open encoded temporal selection over some or all streams of a media asset.

• Stability: stable
• Storage: struct { media, stream_indices, start, end }
• Aliases: spql.media.ClipRef

Fields

spql.EncodedMediaCopy Anchor Link

Blob-backed encoded temporal media with an optional container name and index.

• Stability: stable
• Storage: struct { source, container, index }
• Aliases: spql.media.EncodedMedia

Fields

spql.EncodedPacketCopy Anchor Link

A normalized encoded packet with exact timing in its stream's time base and a Blob payload.

• Stability: stable
• Storage: struct { payload, stream, codec, framing, pts, dts, duration_ticks, time_base_num, time_base_den, keyframe, codec_config }
• Aliases: spql.media.EncodedPacket

Fields

spql.MediaIndexCopy Anchor Link

Index of one encoded media value: per track, the container's sample tables and a GOP table, from which presentation order, byte offsets and each frame's decode closure are derived on read. Row data, never layout or dtype metadata; an EncodedMedia carries it in its index field.

• Stability: experimental
• Storage: struct { primary_track_id, tracks }

Fields

spql.StreamRefCopy Anchor Link

A stream selected from one encoded media asset by its structural container index.

• Stability: stable
• Storage: struct { media, stream_index }
• Aliases: spql.media.StreamRef

Fields

ImagesCopy Anchor Link

spql.EncodedImageCopy Anchor Link

A lazy encoded image over a Blob with the facts a header read can give.

• Stability: stable
• Storage: struct { source, format, mime_type, width, height }
• Aliases: spql.image.EncodedImage

Fields

spql.ImageCopy Anchor Link

Decoded display image: contiguous top-left-origin HWC pixels, treated as sRGB. Each row's pixel_format fixes its channel layout: 1 is RGB8 and 2 is RGBA8 with straight alpha.

• Stability: stable
• Storage: struct { data, width, height, pixel_format }
• Frame: image pixels, top-left origin
• Aliases: spql.image.Image

Fields

spql.Yuv420ImageCopy Anchor Link

Decoded planar 8-bit YUV 4:2:0 image with coded and display sizes, per-plane strides and colour metadata. Timing stays on the frame row.

• Stability: stable
• Storage: struct { y, u, v, coded_width, coded_height, display_width, display_height, y_stride, u_stride, v_stride, range, matrix, primaries, transfer }
• Aliases: spql.image.Yuv420Image

Fields

VideoCopy Anchor Link

spql.FrameIndicesCopy Anchor Link

Ordered presentation-frame positions for spql.video.read. Order and duplicates are preserved.

• Stability: experimental
• Storage: struct { indices }
• Aliases: spql.video.selection.FrameIndices

Fields

spql.FrameNeighborhoodCopy Anchor Link

A fixed-count frame neighborhood around a presentation time, for spql.video.read.

• Stability: experimental
• Storage: struct { time, count, start_offset, step, mode, boundary }
• Aliases: spql.video.selection.FrameNeighborhood

Fields

spql.FrameRefCopy Anchor Link

One presentation frame without pixels. A valid row sets exactly one of stream, resolved through the media's index, or packets, the decode-order packets of the MCAP path.

• Stability: stable
• Storage: struct { stream, packets, presentation_index, decode_index, pts, dts, duration_ticks, time_base_num, time_base_den, keyframe, group_id, local_index, codec_config }
• Aliases: spql.video.FrameRef

Fields

spql.FrameSliceCopy Anchor Link

A half-open slice over display-order presentation-frame positions, for spql.video.read.

• Stability: experimental
• Storage: struct { start, stop, step }
• Aliases: spql.video.selection.FrameSlice

Fields

spql.FrameTimesCopy Anchor Link

Ordered presentation times that spql.video.read resolves to frames. Order and duplicates are preserved.

• Stability: experimental
• Storage: struct { times, mode }
• Aliases: spql.video.selection.FrameTimes

Fields

spql.ImageSequenceCopy Anchor Link

Encoded images in presentation order at a fixed rate; every frame decodes alone.

• Stability: experimental
• Storage: struct { images, frame_rate }
• Aliases: spql.video.ImageSequence

Fields

AudioCopy Anchor Link

spql.AudioBufferCopy Anchor Link

Decoded PCM samples.

• Stability: experimental
• Storage: struct { data, sample_format, sample_rate, channels }

Fields

Depth MapsCopy Anchor Link

spql.DepthMapCopy Anchor Link

A two-dimensional depth value: rank-two f32 sample and confidence tensors shaped [height, width], the representation of the samples and an optional linear calibration.

• Stability: stable
• Storage: struct { values, confidence, width, height, representation, unit, scale, offset }
• Frame: image pixels, top-left origin
• Aliases: spql.depth.DepthMap

Fields

Object DetectionCopy Anchor Link

spql.LabeledBoxCopy Anchor Link

A labeled axis-aligned bounding box with optional confidence.

• Stability: stable
• Storage: struct { label, bbox, score }
• Frame: image pixels, top-left origin
• Aliases: spql.detect.LabeledBox

Fields

AnnotationsCopy Anchor Link

spql.Annotations2DCopy Anchor Link

Collection of image-space annotations.

• Stability: experimental
• Storage: struct { circles, points, text }
• Frame: image pixels, top-left origin

Fields

spql.Circle2DCopy Anchor Link

Styled image-space circle.

• Stability: experimental
• Storage: struct { center, radius, thickness, fill_color, outline_color, metadata }
• Frame: image pixels, top-left origin

Fields

spql.Text2DCopy Anchor Link

Styled image-space text annotation.

• Stability: experimental
• Storage: struct { position, text, color, background_color, font_size, metadata }
• Frame: image pixels, top-left origin

Fields

CamerasCopy Anchor Link

spql.CameraCalibrationCopy Anchor Link

Foxglove CameraCalibration and ROS CameraInfo fields; a pinhole has no distortion.

• Stability: experimental
• Storage: struct { width, height, distortion_model, distortion_coefficients, intrinsic, rectification, projection }

Fields

Point CloudsCopy Anchor Link

spql.EncodedPointCloudCopy Anchor Link

An encoded point cloud, such as PCD, LAS, LAZ or Draco, over a Blob.

• Stability: experimental
• Storage: struct { source, format, pose }

Fields

spql.GridCopy Anchor Link

A two-dimensional grid of packed cells; Foxglove Grid layout.

• Stability: experimental
• Storage: struct { pose, column_count, cell_size, row_stride, cell_stride, fields, data }

Fields

spql.LaserScanCopy Anchor Link

Planar range scan sample.

• Stability: experimental
• Storage: struct { pose, start_angle, end_angle, ranges, intensities }

Fields

spql.PointCloudCopy Anchor Link

Packed points with a field table; Foxglove PointCloud and ROS PointCloud2 layout.

• Stability: experimental
• Storage: struct { pose, point_stride, fields, data }

Fields

Poses and TransformsCopy Anchor Link

spql.Points2DCopy Anchor Link

Aligned two-dimensional point components.

• Stability: experimental
• Storage: struct { positions, colors, radii, labels, topology }
• Units: REP 103 (metres, radians); frame by column

Fields

spql.Points3DCopy Anchor Link

Aligned three-dimensional point components.

• Stability: experimental
• Storage: struct { positions, colors, radii, labels }
• Units: REP 103 (metres, radians); frame by column

Fields

spql.Pose3DCopy Anchor Link

Position and orientation of one object in the row's frame.

• Stability: stable
• Storage: struct { position, orientation }
• Units: REP 103 (metres, radians); frame by column

Fields

spql.Position2DCopy Anchor Link

Two-dimensional position in a declared coordinate system.

• Stability: stable
• Storage: struct { x, y }
• Units: REP 103 (metres, radians); frame by column

Fields

spql.Position3DCopy Anchor Link

Three-dimensional position in a declared coordinate system.

• Stability: stable
• Storage: struct { x, y, z }
• Units: REP 103 (metres, radians); frame by column

Fields

spql.QuaternionCopy Anchor Link

Unit quaternion in x, y, z, w order.

• Stability: stable
• Storage: struct { x, y, z, w }
• Units: REP 103 (metres, radians); frame by column

Fields

spql.Transform3DCopy Anchor Link

Rigid or similarity transform from the child frame to the parent frame.

• Stability: stable
• Storage: struct { translation, rotation, scale, parent_frame_id, child_frame_id }
• Units: REP 103 (metres, radians); frame by column

Fields

spql.Vector2DCopy Anchor Link

Two-dimensional direction or displacement.

• Stability: stable
• Storage: struct { x, y }
• Units: REP 103 (metres, radians); frame by column

Fields

spql.Vector3DCopy Anchor Link

Three-dimensional direction or displacement.

• Stability: stable
• Storage: struct { x, y, z }
• Units: REP 103 (metres, radians); frame by column

Fields

KinematicsCopy Anchor Link

spql.JointStateCopy Anchor Link

Instantaneous state of one revolute or prismatic joint.

• Stability: experimental
• Storage: struct { name, position, velocity, acceleration, effort }

Fields

NavigationCopy Anchor Link

spql.GeoPositionCopy Anchor Link

Geographic position in latitude, longitude, and altitude.

• Stability: experimental
• Storage: struct { latitude, longitude, altitude }

Fields

spql.LocationFixCopy Anchor Link

Instantaneous geographic location estimate.

• Stability: experimental
• Storage: struct { position, covariance, covariance_type, heading, velocity, color, metadata }

Fields

spql.OdometryCopy Anchor Link

Instantaneous pose and velocity estimate.

• Stability: experimental
• Storage: struct { pose, linear_velocity, angular_velocity, pose_covariance, velocity_covariance, metadata }

Fields

ScenesCopy Anchor Link

spql.Arrow3DCopy Anchor Link

Posed three-dimensional arrow.

• Stability: experimental
• Storage: struct { pose, shaft_length, shaft_diameter, head_length, head_diameter, color }

Fields

spql.Box3DCopy Anchor Link

Posed three-dimensional box.

• Stability: experimental
• Storage: struct { pose, size, color }

Fields

spql.ColorCopy Anchor Link

Unit-interval RGBA color.

• Stability: stable
• Storage: struct { r, g, b, a }

Fields

spql.Cylinder3DCopy Anchor Link

Posed cylinder or frustum.

• Stability: experimental
• Storage: struct { pose, size, top_scale, bottom_scale, color }

Fields

spql.Line3DCopy Anchor Link

Posed three-dimensional line topology.

• Stability: experimental
• Storage: struct { pose, points, color, colors, indices, topology, thickness, scale_invariant }

Fields

spql.Mesh3DCopy Anchor Link

Posed triangle mesh.

• Stability: experimental
• Storage: struct { pose, vertices, indices, color, colors }

Fields

spql.Model3DCopy Anchor Link

Posed model asset reference or embedded payload.

• Stability: experimental
• Storage: struct { pose, scale, source, media_type, color, override_color }

Fields

spql.SceneEntity3DCopy Anchor Link

Identified collection of three-dimensional primitives.

• Stability: experimental
• Storage: struct { id, frame_id, lifetime_ns, frame_locked, arrows, boxes, cylinders, spheres, lines, meshes, text, models, metadata }
• Frame: frame_id field: the frame its primitives are posed in

Fields

spql.SceneEntityDeletionCopy Anchor Link

Deletion of one matching scene entity or all entities.

• Stability: experimental
• Storage: struct { id, all }

Fields

spql.SceneUpdate3DCopy Anchor Link

Ordered additions, replacements, and deletions for a 3D scene.

• Stability: experimental
• Storage: struct { entities, deletions }

Fields

spql.Sphere3DCopy Anchor Link

Posed ellipsoid.

• Stability: experimental
• Storage: struct { pose, size, color }

Fields

spql.Text3DCopy Anchor Link

Posed three-dimensional text.

• Stability: experimental
• Storage: struct { pose, text, color, font_size, billboard, scale_invariant }

Fields

LogsCopy Anchor Link

spql.LogEntryCopy Anchor Link

One structured log record.

• Stability: experimental
• Storage: struct { level, message, name, file, line }

Fields

TensorsCopy Anchor Link

spql.TensorCopy Anchor Link

A dense tensor whose shape may differ from value to value, with optional dimension names, the permutation from logical to physical dimensions and the dimension sizes every value shares, as Arrow's canonical variable-shape tensor defines them.

• Stability: stable
• Storage: struct {data: list<E>, shape: fixed_size_list<i32, N>}, written spql.Tensor<E, N> in field types: the row-major samples of primitive type E and the sizes of the tensor's N dimensions. dim_names, permutation and uniform_shape, when present, have one entry per dimension.
• Aliases: vortex.tensor.variable_shape_tensor
• Arrow extension name: arrow.variable_shape_tensor

Type parameters

vortex.tensor.fixed_shape_tensorCopy Anchor Link

A dense primitive tensor with the same logical shape for every value. Dimension names describe logical dimensions; permutation[i] gives the physical dimension for logical dimension i. Without a permutation, logical and physical order are identical.

• Defined by: the Vortex file format
• Storage: fixed_size_list<E, product(shape)>, where E is a non-nullable primitive element type. Optional names and permutation each have one entry per dimension.
• Arrow extension name: arrow.fixed_shape_tensor

Type parameters

vortex.tensor.vectorCopy Anchor Link

A fixed-length one-dimensional vector of non-nullable floating-point elements.

• Defined by: the Vortex file format
• Storage: fixed_size_list<E, N>, where E is f16, f32 or f64 and N is the vector dimension. The element type and dimension come from the storage; there are no metadata parameters.

Vector QuantizationCopy Anchor Link

spql.RaBitQCopy Anchor Link

A vector quantized with RaBitQ for approximate distance estimation: sign codes and optional extra-bit codes of its coordinates after a deterministic rotation, with the per-row factors that correct the estimate.

• Stability: stable
• Storage: struct {signs, extra_codes?, norm_sq, one_bit_scale, full_scale?, full_error_scale?, error_scale}: fixed_size_list<u8, code_dimensions> sign codes, extra-bit codes when num_bits is above 1, and per-row f32 or f64 correction factors, the multi-bit ones when num_bits is above 1.
• Aliases: vortex.rabitq

Type parameters

vortex.turboquantCopy Anchor Link

A vector compressed with TurboQuant: split into blocks, each stored as its norm and the scalar-quantized coordinates of its unit direction after a structured random rotation. Lossy; spql.vector.dequantize decodes it.

• Stability: stable
• Defined by: the Vortex file format
• Storage: struct {block_0: struct {norms: E, codes: fixed_size_list<u8, B0>}, ...}: one struct per entry of block_sizes, holding each row's norm of type element_ptype and one quantizer code per coordinate of the block.

Type parameters

GeospatialCopy Anchor Link

vortex.st.boxCopy Anchor Link

Exports to Arrow as geoarrow.box.

• Defined by: the Vortex file format
• Arrow extension name: geoarrow.box

vortex.st.linestringCopy Anchor Link

Exports to Arrow as geoarrow.linestring.

• Defined by: the Vortex file format
• Arrow extension name: geoarrow.linestring

vortex.st.multilinestringCopy Anchor Link

Exports to Arrow as geoarrow.multilinestring.

• Defined by: the Vortex file format
• Arrow extension name: geoarrow.multilinestring

vortex.st.multipointCopy Anchor Link

Exports to Arrow as geoarrow.multipoint.

• Defined by: the Vortex file format
• Arrow extension name: geoarrow.multipoint

vortex.st.multipolygonCopy Anchor Link

Exports to Arrow as geoarrow.multipolygon.

• Defined by: the Vortex file format
• Arrow extension name: geoarrow.multipolygon

vortex.st.pointCopy Anchor Link

Exports to Arrow as geoarrow.point.

• Defined by: the Vortex file format
• Arrow extension name: geoarrow.point

vortex.st.polygonCopy Anchor Link

Exports to Arrow as geoarrow.polygon.

• Defined by: the Vortex file format
• Arrow extension name: geoarrow.polygon

vortex.st.wkbCopy Anchor Link

Exports to Arrow as geoarrow.wkb.

• Defined by: the Vortex file format
• Arrow extension name: geoarrow.wkb