type Key = Uint8ArrayA run of several identities is the same type with a length that is a multiple of
keyBytes, which is what lets one batch of keys cross as one array.
A key is sixteen opaque bytes, most significant first, and that is the only form a full 128-bit key survives.
Matches carry them as one Uint8Array of sixteen bytes per match, which is byte-for-byte what the engine writes, so a batch of results needs no conversion pass and no object per match.
The canonical rendering is the lowercase dashed UUID the ABI fixes, and that is a rendering rather than a second carrier.
usearch.keyFromInteger(42n); // Uint8Array(16), 42 in the trailing byte
usearch.formatKey(usearch.keyFromInteger(42n)); // '00000000-0000-0000-0000-00000000002a'
usearch.parseKey('f81d4fae-7dec-11d0-a765-00a0c91e6bf6'); // Uint8Array(16)
usearch.keyAt(matches.keys, 0); // the first key, as a view rather than a copy
usearch.integerFromKey(usearch.keyAt(matches.keys, 0)); // its integer, when it was inserted as oneAn integer key parks in the trailing eight bytes with the leading eight zeroed, so 42n prints as 00000000-0000-0000-0000-00000000002a. integerFromKey throws on a key whose leading bytes carry anything, since no integer spells it.
Keys are accepted in every one of those spellings, plus a BigUint64Array of integer keys, which stays the convenient path for services that number their entries:
index.insert(42n, vector); // a BigInt
index.insert(new BigUint64Array([15n, 16n]), vectors); // a run of integers
index.insert('f81d4fae-7dec-11d0-a765-00a0c91e6bf6', vector); // a dashed UUID
index.insert(usearch.parseKey('f81d4fae-7dec-11d0-a765-00a0c91e6bf6'), vector); // bytesA single key broadcasts across every row of a batch, and a Uint8Array of keys crosses without a copy.
API
Types
KeySixteen opaque bytes, most significant first - one identity, losslessly.
KeyLikeEvery spelling one identity is accepted in.
type KeyLike = bigint | number | string | Uint8ArrayKeysLikeEvery spelling a run of identities is accepted in.
type KeysLike = KeyLike | BigUint64Array | Array<bigint | number | string | Uint8Array>Functions
keyFromIntegerParks an integer identity in the trailing eight bytes, most significant first.
function keyFromInteger(value: bigint | number): KeyBinding-only.
Parameters
valuebigint | number | A non-negative integer below 2^64. |
|---|
Returns
The sixteen identity bytes, the leading eight zeroed.
integerFromKeyReports the integer identity in the trailing eight bytes.
function integerFromKey(key: Uint8Array): bigintBinding-only.
Parameters
keyUint8Array | Sixteen identity bytes. |
|---|
Returns
The integer the trailing eight bytes spell.
Throws
Will throw an error if the leading eight bytes carry anything, since no integer spells that identity.
formatKeyRenders one identity as a lowercase dashed UUID, which is how every SDK prints it.
function formatKey(key: Uint8Array): stringBinding-only.
Parameters
keyUint8Array | Sixteen identity bytes. |
|---|
Returns
Thirty-six characters, dashed after the 4th, 6th, 8th and 10th byte.
parseKeyReads the rendering formatKey produces.
function parseKey(text: string): KeyDashes may sit anywhere, or nowhere. Binding-only.
Parameters
textstring | Thirty-two hexadecimal digits, dashes ignored. |
|---|
Returns
The sixteen identity bytes.
keyAtBorrows the identity at position of a run, as a view rather than a copy.
function keyAt(keys: Uint8Array, position: number): KeyBinding-only.
Parameters
keysUint8Array | A run of sixteen-byte identities. | |
|---|---|---|
positionnumber | Which identity to borrow. |
Returns
A view over those sixteen bytes, backed by the run's own storage.
Constants
keyBytesBytes one identity occupies, on the wire and in the engine alike.
const keyBytes: 16