BinData subtype-aware aggregation dispatch and invalid inputs
Parent: BSON BinData vector ingestion · Published reference · snapshot 2026-10-29
↓ Facts as markdownall context files
Source-anchored research for BinData subtype-aware aggregation dispatch and invalid inputs. Run status: COMPLETED.
These notes link each claim to its source. Some citations identify archived research reports that are no longer hosted on this site. A published reference means the content is available; it does not certify independent review or accuracy.Read the editorial policy and follow the sources before relying on a claim.
How it works
- The 8.3 cosine and Euclidean similarity operator contracts accept arrays or BinData and return null when either input is null or missing. Both reject unsupported input types, unequal vector lengths, and non-numeric array elements. SERVER-113013 separately records the addition of BinData vector inputs. (high confidence) (verified as of 2026-10-14) [source]
Problems, failure modes and limitations
- $subtype returns null for null or missing input; other expressions without a subtype error. MongoDB 8.3 documents BinData as the only supported subtype-bearing value. (low confidence) [source]
- Starting in 8.1, $convert rejects conversion between different BinData subtypes; 8.0 instead returned the original value and subtype. The r8.3.0 implementation checks subtype equality, so requesting subtype 9 cannot relabel arbitrary subtype-0 bytes into a vector. (high confidence) (verified as of 2026-10-27) [source]
- The r8.3.0 parser test rejects two $subtype arguments with error 16020. An ingestion expression must supply exactly one operand; a list of candidate values is not a batch subtype-inspection request. (low confidence) [source]
- Use $convert with onError for recoverable conversion failures and onNull for null or missing input. $toArray uses the default conversion behavior: a conversion error stops the aggregation, while null or missing input yields null. (medium confidence) [source]
Comparisons and alternatives
- In r8.3.0, converting [NumberInt(200)] to BinData fails because array dtype selection rejects BSON int values outside [-128,127], rather than automatically widening them to FLOAT32. SERVER-106059 records the same example and proposed alternatives; its description is historical evidence, not proof of all later releases. (high confidence) [source]
- The vector specification requires FLOAT32 payload length after the two metadata bytes to be divisible by four. Non-PACKED_BIT padding must be zero; PACKED_BIT padding must be 0–7, and nonzero padding requires nonempty data. These requirements apply to vector APIs and decoding into vector structures, rather than establishing that every generic BSON operation validates vectors. (low confidence) [source]
Facts and statements
- MongoDB documents $subtype as new in 8.3: {$subtype: <expression>} returns the integer BinData subtype. COMPASS-9668 describes a prior $function-based inspection workaround and the need for native aggregation inspection. (high confidence) (verified as of 2026-10-14) [source]
- A heterogeneous ingestion pipeline can first test {$type: '$v'} for 'binData', then evaluate $subtype inside the matching conditional branch and route subtype 9 to vector handling. This is a derived dispatch pattern: $type identifies the outer BSON type, while $subtype identifies the binary subtype. (medium confidence) [source]
- The r8.3.0 subtype tests return the integer tag for named BinData types including Vector and for custom subtype 200. These tests inspect a tag on fixed test bytes; a subtype value alone is not proof that a payload represents a valid vector. (low confidence) [source]
- After its feature/FCV check enables vector conversion, the r8.3.0 implementation rejects BinData-to-array conversion unless the input subtype is Vector (9), with ConversionFailure: Conversion from binData to array is only supported for bindata with the vector subtype. Conversion delegates vector decoding to convertBinDataVectorToArray after this check. (low confidence) [source]
- In r8.3.0, $convert.onError handles ConversionFailure exceptions from performConversion. Target-type parsing and format/byteOrder validation occur outside that catch, and invalid subtype checks use separate assertion codes 4341106, 4341107 and 4341108. Do not treat onError as a universal catch for malformed conversion configuration. (low confidence) [source]
- The r8.3.0 array-to-BinData implementation always constructs subtype Vector after selecting an internal dtype; it does not use the supplied subtypeValue parameter for the resulting BinData tag. This behavior is specific to that tagged implementation and should not be inferred from the generic to.subtype documentation. (low confidence) [source]
- A historical issue titled Conversions to bindata do not preserve, set, or check correct subtypes (SERVER-105121) was resolved Works as Designed. Its example and proposed audit do not establish a currently unfixed defect or a guarantee that every conversion validates a subtype-specific payload. (low confidence) (verified as of 2025-10-02) [source]
- MongoDB documents $subtype as new in 8.3: {$subtype: <expression>} returns a BinData value's subtype as an integer. The r8.3.0 tests cover predefined subtypes including Vector and also return 200 for an unnamed subtype. (medium confidence) (verified as of 2026-10-14) [source]
- A subtype match is insufficient to establish vector-payload validity. The r8.3.0 subtype tests attach arbitrary bytes to the Vector subtype and still obtain its integer tag; the vector specification separately requires metadata and payload validation. (medium confidence) [source]
- BinData-to-array conversion is subtype-sensitive: r8.3.0 $convert rejects binary input whose subtype is not Vector (9), then invokes vector decoding. $toArray documents subtype-9 input and maps PACKED_BIT to booleans, INT8 to integers, and FLOAT32 to doubles. (medium confidence) [source]
- In r8.3.0, $convert subtype validation uses errors 4341106 for a non-integral numeric subtype, 4341107 for an invalid subtype code, and 4341108 for a nonnumeric subtype. Its onError handler catches ConversionFailure specifically, so these argument-validation assertions are not covered by that handler. (low confidence) [source]
- An independent Apache Phoenix branch commit, 509ce3014 dated 2026-10-06, implements BSON_VECTOR_VALUE checks for subtype 9, a two-byte header, FLOAT32 dtype, zero padding, finite elements, and expected dimension. This is evidence for that branch's extraction boundary, not MongoDB aggregation semantics or a released Phoenix feature. (low confidence) [source]
- Variety's own schema-analyzer documentation distinguishes subtype-9 INT8, PACKED_BIT, and FLOAT32 labels and provides fallback labels for unknown dtype bytes and malformed payloads. This independently illustrates subtype-aware inspection tooling; it does not verify MongoDB server acceptance. (low confidence) (verified as of 2026-10-27) [source]
Children
- No children recorded.