query,

source,

metadata,

topK = 10,

metric,

rerankFactor = 10,

probe,

binary,

algorithm = 'auto',

signal,

asyncBufferFactory,

compressors,

}) {

if (source === undefined || source === null) {

throw new Error('searchVectors: `source` is required (URL, file path, or AsyncBuffer)')

}

// negated comparison so NaN is rejected too: a NaN topK sizes the

// candidate heap as unbounded and exhausts memory

if (!(topK > 0)) {

throw new Error(`searchVectors: \`topK\` must be positive: ${topK}`)

}

if (!(rerankFactor >= 0)) {

throw new Error(`searchVectors: \`rerankFactor\` must be non-negative: ${rerankFactor}`)

}

const sources = Array.isArray(source) ? source : [source]

if (sources.length === 0) {

throw new Error('searchVectors: `source` array is empty')

}

if (Array.isArray(metadata) && metadata.length !== sources.length) {

throw new Error(`searchVectors: \`metadata\` array length ${metadata.length} does not match \`source\` array length ${sources.length}`)

}

if (Array.isArray(binary) && binary.length !== sources.length) {

throw new Error(`searchVectors: \`binary\` array length ${binary.length} does not match \`source\` array length ${sources.length}`)

}

const metadatas = Array.isArray(metadata) ? metadata : sources.map(() => metadata)

const binaries = Array.isArray(binary) ? binary : sources.map(() => binary)

const multi = sources.length > 1

const perSource = await Promise.all(sources.map((src, i) => searchOne({

query,

source: src,

metadata: metadatas[i],

binary: binaries[i],

topK,

metric,

rerankFactor,

probe,

signal,

algorithm,

asyncBufferFactory,

compressors,

sourceIndex: multi ? i : undefined,

})))

if (!multi) return perSource[0].results

// Merge: each per-source array is already sorted best-first under the same

// direction (we assert below). Flatten, sort, slice — N is small.

const { direction } = perSource[0]

for (let i = 1; i < perSource.length; i += 1) {

if (perSource[i].direction !== direction) {

throw new Error('searchVectors: sources have inconsistent metric directions')

}

}

const merged = perSource.flatMap(p => p.results)

merged.sort((a, b) => direction * (a.score - b.score))

return merged.slice(0, topK)

query, source, metadata: providedMetadata, binary, topK, metric, rerankFactor, probe, algorithm, signal, asyncBufferFactory, compressors, sourceIndex,

}) {

const file = typeof source === 'string'

? await (asyncBufferFactory ?? defaultAsyncBufferFactory)({ source, signal })

: source

const metadata = providedMetadata ?? await parquetMetadataAsync(file)

const meta = parseKvMetadata(metadata)

if (query.length !== meta.dimension) {

throw new Error(`query has dimension ${query.length}, file expects ${meta.dimension}`)

}

const requestedMetric = metric ?? meta.metric

let queryF32 = query instanceof Float32Array ? query : Float32Array.from(query)

// When stored vectors are pre-normalized, cosine == dot(query/||query||, candidate).

let scoringMetric = requestedMetric

if (requestedMetric === 'cosine' && meta.normalized) {

queryF32 = l2Normalize(queryF32)

scoringMetric = 'dot'

}

/** @type {SearchResult[]} */

let results

if (algorithm === 'exact' || rerankFactor === 0) {

results = await searchExact({

file, metadata, meta, queryF32, scoringMetric, reportedMetric: requestedMetric, topK, compressors,

})

} else if (algorithm === 'binary') {

if (!meta.hasBinary) throw new Error('searchVectors: algorithm `binary` requested, but file has no binary column')

results = await searchRerank({

file, metadata, meta, queryF32, scoringMetric, reportedMetric: requestedMetric, topK, rerankFactor, probe, binary, compressors,

})

} else if (algorithm !== 'auto') {

throw new Error(`searchVectors: unsupported algorithm ${algorithm}`)

} else if (meta.hasBinary) {

results = await searchRerank({

file, metadata, meta, queryF32, scoringMetric, reportedMetric: requestedMetric, topK, rerankFactor, probe, binary, compressors,

})

} else {

results = await searchExact({

file, metadata, meta, queryF32, scoringMetric, reportedMetric: requestedMetric, topK, compressors,

})

}

if (sourceIndex !== undefined) {

for (const r of results) r.sourceIndex = sourceIndex

}

const direction = requestedMetric === 'euclidean' ? 1 : -1

return { results, direction }