sqlite-vec.c

// Enable POSIX large-file offsets and fseeko()/ftello() declarations, including
// when downstream builds use strict ISO C compiler flags.
#if !defined(_WIN32) && !defined(SQLITE_VEC_OMIT_FS)
#ifndef _FILE_OFFSET_BITS
#define _FILE_OFFSET_BITS 64
#endif
#ifndef _POSIX_C_SOURCE
#define _POSIX_C_SOURCE 200809L
#endif
#endif

#include "sqlite-vec.h"

#include <assert.h>
#include <errno.h>
#include <float.h>
#include <inttypes.h>
#include <limits.h>
#include <math.h>
#include <stdarg.h>
#include <stdbool.h>
#include <stdint.h>
#include <stdlib.h>
#include <string.h>

#ifndef SQLITE_VEC_OMIT_FS
#include <stdio.h>
#endif

#ifndef SQLITE_CORE
#include "sqlite3ext.h"
SQLITE_EXTENSION_INIT1
#else
#include "sqlite3.h"
#endif

typedef int8_t i8;
typedef uint8_t u8;
typedef int16_t i16;
typedef int32_t i32;
typedef sqlite3_int64 i64;
typedef uint32_t u32;
typedef uint64_t u64;
typedef float f32;
typedef size_t usize;

#ifndef UNUSED_PARAMETER
#define UNUSED_PARAMETER(X) (void)(X)
#endif

// sqlite3_vtab_in() was added in SQLite version 3.38 (2022-02-22)
// https://www.sqlite.org/changes.html#version_3_38_0
#if SQLITE_VERSION_NUMBER >= 3038000
#define COMPILER_SUPPORTS_VTAB_IN 1
#endif

// sqlite3_value_encoding() was added in SQLite version 3.41 (2023-02-21)
// https://www.sqlite.org/changes.html#version_3_41_0
#if SQLITE_VERSION_NUMBER >= 3041000
#define COMPILER_SUPPORTS_VALUE_ENCODING 1
#endif

#ifndef SQLITE_SUBTYPE
#define SQLITE_SUBTYPE 0x000100000
#endif

#ifndef SQLITE_RESULT_SUBTYPE
#define SQLITE_RESULT_SUBTYPE 0x001000000
#endif

#ifndef SQLITE_INDEX_CONSTRAINT_LIMIT
#define SQLITE_INDEX_CONSTRAINT_LIMIT 73
#endif

#ifndef SQLITE_INDEX_CONSTRAINT_OFFSET
#define SQLITE_INDEX_CONSTRAINT_OFFSET 74
#endif

#define countof(x) (sizeof(x) / sizeof((x)[0]))
#define min(a, b) (((a) <= (b)) ? (a) : (b))

// VEC0_UNPREDICTABLE(cond) tells clang that cond is hard to predict, so it
// emits a conditional move instead of a branch. Other compilers get cond as is.
#if defined(__has_builtin)
#if __has_builtin(__builtin_unpredictable)
#define VEC0_UNPREDICTABLE(x) __builtin_unpredictable(x)
#endif
#endif
#ifndef VEC0_UNPREDICTABLE
#define VEC0_UNPREDICTABLE(x) (x)
#endif

// Locale-independent strtod implementation for parsing JSON floats
// Fixes issue #241: strtod is locale-dependent and breaks with non-C locales
//
// This custom parser always uses '.' as decimal separator regardless of locale.
// Simpler and more portable than strtod_l, with no thread-safety issues.
static double strtod_c(const char *str, char **endptr) {
  const char *p = str;
  double result = 0.0;
  int sign = 1;
  int has_digits = 0;

  // Skip leading whitespace
  while (*p == ' ' || *p == '\t' || *p == '\n' || *p == '\r') {
    p++;
  }

  // Handle optional sign
  if (*p == '-') {
    sign = -1;
    p++;
  } else if (*p == '+') {
    p++;
  }

  // Parse integer part
  while (*p >= '0' && *p <= '9') {
    result = result * 10.0 + (*p - '0');
    p++;
    has_digits = 1;
  }

  // Parse fractional part
  if (*p == '.') {
    double fraction = 0.0;
    double divisor = 1.0;
    p++;

    while (*p >= '0' && *p <= '9') {
      fraction = fraction * 10.0 + (*p - '0');
      divisor *= 10.0;
      p++;
      has_digits = 1;
    }

    result += fraction / divisor;
  }

  // Parse exponent
  if ((*p == 'e' || *p == 'E') && has_digits) {
    int exp_sign = 1;
    int exponent = 0;
    p++;

    if (*p == '-') {
      exp_sign = -1;
      p++;
    } else if (*p == '+') {
      p++;
    }

    while (*p >= '0' && *p <= '9') {
      // clamp: any exponent this large already over/underflows a double,
      // and accumulating further would overflow the int itself
      if (exponent < 10000) {
        exponent = exponent * 10 + (*p - '0');
      }
      p++;
    }

    // Apply exponent using pow() for accuracy
    if (exponent > 0) {
      double exp_mult = pow(10.0, (double)exponent);
      if (exp_sign == 1) {
        result *= exp_mult;
      } else {
        result /= exp_mult;
      }
    }
  }

  // Set end pointer
  if (endptr) {
    *endptr = (char *)(has_digits ? p : str);
  }

  // Check for overflow/underflow
  if (result == HUGE_VAL || result == -HUGE_VAL) {
    errno = ERANGE;
  }

  return sign * result;
}

enum VectorElementType {
  // clang-format off
  SQLITE_VEC_ELEMENT_TYPE_FLOAT32 = 223 + 0,
  SQLITE_VEC_ELEMENT_TYPE_BIT     = 223 + 1,
  SQLITE_VEC_ELEMENT_TYPE_INT8    = 223 + 2,
  // clang-format on
};

#ifdef SQLITE_VEC_ENABLE_AVX
#include <immintrin.h>
#define PORTABLE_ALIGN32 __attribute__((aligned(32)))
#define PORTABLE_ALIGN64 __attribute__((aligned(64)))

static f32 l2_sqr_float_avx(const void *pVect1v, const void *pVect2v,
                            const void *qty_ptr) {
  f32 *pVect1 = (f32 *)pVect1v;
  f32 *pVect2 = (f32 *)pVect2v;
  size_t qty = *((size_t *)qty_ptr);
  f32 PORTABLE_ALIGN32 TmpRes[8];
  size_t qty16 = qty >> 4;

  const f32 *pEnd1 = pVect1 + (qty16 << 4);

  __m256 diff, v1, v2;
  __m256 sum = _mm256_set1_ps(0);

  while (pVect1 < pEnd1) {
    v1 = _mm256_loadu_ps(pVect1);
    pVect1 += 8;
    v2 = _mm256_loadu_ps(pVect2);
    pVect2 += 8;
    diff = _mm256_sub_ps(v1, v2);
    sum = _mm256_add_ps(sum, _mm256_mul_ps(diff, diff));

    v1 = _mm256_loadu_ps(pVect1);
    pVect1 += 8;
    v2 = _mm256_loadu_ps(pVect2);
    pVect2 += 8;
    diff = _mm256_sub_ps(v1, v2);
    sum = _mm256_add_ps(sum, _mm256_mul_ps(diff, diff));
  }

  _mm256_store_ps(TmpRes, sum);
  return sqrt(TmpRes[0] + TmpRes[1] + TmpRes[2] + TmpRes[3] + TmpRes[4] +
              TmpRes[5] + TmpRes[6] + TmpRes[7]);
}
#endif

#ifdef SQLITE_VEC_ENABLE_NEON
#if defined(_MSC_VER) && !defined(__clang__) && defined(_M_ARM64)
#include <arm64_neon.h>
#else
#include <arm_neon.h>
#endif

#define PORTABLE_ALIGN32 __attribute__((aligned(32)))

// thx https://github.com/nmslib/hnswlib/pull/299/files
static f32 l2_sqr_float_neon(const void *pVect1v, const void *pVect2v,
                             const void *qty_ptr) {
  f32 *pVect1 = (f32 *)pVect1v;
  f32 *pVect2 = (f32 *)pVect2v;
  size_t qty = *((size_t *)qty_ptr);
  size_t qty16 = qty >> 4;

  const f32 *pEnd1 = pVect1 + (qty16 << 4);

  float32x4_t diff, v1, v2;
  float32x4_t sum0 = vdupq_n_f32(0);
  float32x4_t sum1 = vdupq_n_f32(0);
  float32x4_t sum2 = vdupq_n_f32(0);
  float32x4_t sum3 = vdupq_n_f32(0);

  while (pVect1 < pEnd1) {
    v1 = vld1q_f32(pVect1);
    pVect1 += 4;
    v2 = vld1q_f32(pVect2);
    pVect2 += 4;
    diff = vsubq_f32(v1, v2);
    sum0 = vfmaq_f32(sum0, diff, diff);

    v1 = vld1q_f32(pVect1);
    pVect1 += 4;
    v2 = vld1q_f32(pVect2);
    pVect2 += 4;
    diff = vsubq_f32(v1, v2);
    sum1 = vfmaq_f32(sum1, diff, diff);

    v1 = vld1q_f32(pVect1);
    pVect1 += 4;
    v2 = vld1q_f32(pVect2);
    pVect2 += 4;
    diff = vsubq_f32(v1, v2);
    sum2 = vfmaq_f32(sum2, diff, diff);

    v1 = vld1q_f32(pVect1);
    pVect1 += 4;
    v2 = vld1q_f32(pVect2);
    pVect2 += 4;
    diff = vsubq_f32(v1, v2);
    sum3 = vfmaq_f32(sum3, diff, diff);
  }

  f32 sum_scalar =
      vaddvq_f32(vaddq_f32(vaddq_f32(sum0, sum1), vaddq_f32(sum2, sum3)));
  const f32 *pEnd2 = pVect1 + (qty - (qty16 << 4));
  while (pVect1 < pEnd2) {
    f32 diff = *pVect1 - *pVect2;
    sum_scalar += diff * diff;
    pVect1++;
    pVect2++;
  }

  return sqrt(sum_scalar);
}

static f32 l2_sqr_int8_neon(const void *pVect1v, const void *pVect2v,
                            const void *qty_ptr) {
  i8 *pVect1 = (i8 *)pVect1v;
  i8 *pVect2 = (i8 *)pVect2v;
  size_t qty = *((size_t *)qty_ptr);

  const i8 *pEnd1 = pVect1 + qty;
  int64x2_t acc = vdupq_n_s64(0);

  while (pVect1 < pEnd1 - 7) {
    // loading 8 at a time
    int8x8_t v1 = vld1_s8(pVect1);
    int8x8_t v2 = vld1_s8(pVect2);
    pVect1 += 8;
    pVect2 += 8;

    // the difference (up to ±255) fits in 16 bits, but its square (up to
    // 65025) does not, so square with a widening multiply into 32 bits.
    // A 32-bit lane holds two squares, but 33,026 of them overflow it, so
    // the running sum is kept in 64-bit lanes.
    int16x8_t diff = vsubq_s16(vmovl_s8(v1), vmovl_s8(v2));
    int32x4_t squares = vmull_s16(vget_low_s16(diff), vget_low_s16(diff));
    squares = vmlal_high_s16(squares, diff, diff);
    acc = vpadalq_s32(acc, squares);
  }

  i64 sum_scalar = vaddvq_s64(acc);

  // handle leftovers
  while (pVect1 < pEnd1) {
    i16 diff = (i16)*pVect1 - (i16)*pVect2;
    sum_scalar += diff * diff;
    pVect1++;
    pVect2++;
  }

  return sqrtf(sum_scalar);
}

static i32 l1_int8_neon(const void *pVect1v, const void *pVect2v,
                        const void *qty_ptr) {
  i8 *pVect1 = (i8 *)pVect1v;
  i8 *pVect2 = (i8 *)pVect2v;
  size_t qty = *((size_t *)qty_ptr);

  const int8_t *pEnd1 = pVect1 + qty;

  int32x4_t acc1 = vdupq_n_s32(0);
  int32x4_t acc2 = vdupq_n_s32(0);
  int32x4_t acc3 = vdupq_n_s32(0);
  int32x4_t acc4 = vdupq_n_s32(0);

  // vabdq_s8 returns |a - b| (up to 255) in signed lanes, so each difference
  // is reinterpreted as unsigned before the widening pairwise adds
  while (pVect1 < pEnd1 - 63) {
    int8x16_t v1 = vld1q_s8(pVect1);
    int8x16_t v2 = vld1q_s8(pVect2);
    uint8x16_t diff1 = vreinterpretq_u8_s8(vabdq_s8(v1, v2));
    acc1 =
        vaddq_s32(acc1, vreinterpretq_s32_u32(vpaddlq_u16(vpaddlq_u8(diff1))));

    v1 = vld1q_s8(pVect1 + 16);
    v2 = vld1q_s8(pVect2 + 16);
    uint8x16_t diff2 = vreinterpretq_u8_s8(vabdq_s8(v1, v2));
    acc2 =
        vaddq_s32(acc2, vreinterpretq_s32_u32(vpaddlq_u16(vpaddlq_u8(diff2))));

    v1 = vld1q_s8(pVect1 + 32);
    v2 = vld1q_s8(pVect2 + 32);
    uint8x16_t diff3 = vreinterpretq_u8_s8(vabdq_s8(v1, v2));
    acc3 =
        vaddq_s32(acc3, vreinterpretq_s32_u32(vpaddlq_u16(vpaddlq_u8(diff3))));

    v1 = vld1q_s8(pVect1 + 48);
    v2 = vld1q_s8(pVect2 + 48);
    uint8x16_t diff4 = vreinterpretq_u8_s8(vabdq_s8(v1, v2));
    acc4 =
        vaddq_s32(acc4, vreinterpretq_s32_u32(vpaddlq_u16(vpaddlq_u8(diff4))));

    pVect1 += 64;
    pVect2 += 64;
  }

  while (pVect1 < pEnd1 - 15) {
    int8x16_t v1 = vld1q_s8(pVect1);
    int8x16_t v2 = vld1q_s8(pVect2);
    uint8x16_t diff = vreinterpretq_u8_s8(vabdq_s8(v1, v2));
    acc1 =
        vaddq_s32(acc1, vreinterpretq_s32_u32(vpaddlq_u16(vpaddlq_u8(diff))));
    pVect1 += 16;
    pVect2 += 16;
  }

  int32x4_t acc = vaddq_s32(vaddq_s32(acc1, acc2), vaddq_s32(acc3, acc4));

  int32_t sum = 0;
  while (pVect1 < pEnd1) {
    int32_t diff = abs((int32_t)*pVect1 - (int32_t)*pVect2);
    sum += diff;
    pVect1++;
    pVect2++;
  }

  return vaddvq_s32(acc) + sum;
}

static double l1_f32_neon(const void *pVect1v, const void *pVect2v,
                          const void *qty_ptr) {
  f32 *pVect1 = (f32 *)pVect1v;
  f32 *pVect2 = (f32 *)pVect2v;
  size_t qty = *((size_t *)qty_ptr);

  const f32 *pEnd1 = pVect1 + qty;
  float64x2_t acc = vdupq_n_f64(0);

  while (pVect1 < pEnd1 - 3) {
    float32x4_t v1 = vld1q_f32(pVect1);
    float32x4_t v2 = vld1q_f32(pVect2);
    pVect1 += 4;
    pVect2 += 4;

    // f32x4 -> f64x2 pad for overflow
    float64x2_t low_diff = vabdq_f64(vcvt_f64_f32(vget_low_f32(v1)),
                                     vcvt_f64_f32(vget_low_f32(v2)));
    float64x2_t high_diff =
        vabdq_f64(vcvt_high_f64_f32(v1), vcvt_high_f64_f32(v2));

    acc = vaddq_f64(acc, vaddq_f64(low_diff, high_diff));
  }

  double sum = 0;
  while (pVect1 < pEnd1) {
    sum += fabs((double)*pVect1 - (double)*pVect2);
    pVect1++;
    pVect2++;
  }

  return vaddvq_f64(acc) + sum;
}

// asg017/sqlite-vec's cosine_float_neon, with its sums kept in double as
// distance_cosine_float keeps them: each float32x4 load is widened to two
// float64x2 halves before it is multiplied and added.
static f32 cosine_float_neon(const void *pVect1v, const void *pVect2v,
                             const void *qty_ptr) {
  f32 *pVect1 = (f32 *)pVect1v;
  f32 *pVect2 = (f32 *)pVect2v;
  size_t qty = *((size_t *)qty_ptr);
  size_t qty16 = qty >> 4;
  const f32 *pEnd1 = pVect1 + (qty16 << 4);

  float64x2_t dot0 = vdupq_n_f64(0), dot1 = vdupq_n_f64(0);
  float64x2_t dot2 = vdupq_n_f64(0), dot3 = vdupq_n_f64(0);
  float64x2_t amag0 = vdupq_n_f64(0), amag1 = vdupq_n_f64(0);
  float64x2_t amag2 = vdupq_n_f64(0), amag3 = vdupq_n_f64(0);
  float64x2_t bmag0 = vdupq_n_f64(0), bmag1 = vdupq_n_f64(0);
  float64x2_t bmag2 = vdupq_n_f64(0), bmag3 = vdupq_n_f64(0);

  while (pVect1 < pEnd1) {
    float32x4_t v1, v2;
    float64x2_t a, b;

    v1 = vld1q_f32(pVect1);
    pVect1 += 4;
    v2 = vld1q_f32(pVect2);
    pVect2 += 4;
    a = vcvt_f64_f32(vget_low_f32(v1));
    b = vcvt_f64_f32(vget_low_f32(v2));
    dot0 = vfmaq_f64(dot0, a, b);
    amag0 = vfmaq_f64(amag0, a, a);
    bmag0 = vfmaq_f64(bmag0, b, b);
    a = vcvt_high_f64_f32(v1);
    b = vcvt_high_f64_f32(v2);
    dot0 = vfmaq_f64(dot0, a, b);
    amag0 = vfmaq_f64(amag0, a, a);
    bmag0 = vfmaq_f64(bmag0, b, b);

    v1 = vld1q_f32(pVect1);
    pVect1 += 4;
    v2 = vld1q_f32(pVect2);
    pVect2 += 4;
    a = vcvt_f64_f32(vget_low_f32(v1));
    b = vcvt_f64_f32(vget_low_f32(v2));
    dot1 = vfmaq_f64(dot1, a, b);
    amag1 = vfmaq_f64(amag1, a, a);
    bmag1 = vfmaq_f64(bmag1, b, b);
    a = vcvt_high_f64_f32(v1);
    b = vcvt_high_f64_f32(v2);
    dot1 = vfmaq_f64(dot1, a, b);
    amag1 = vfmaq_f64(amag1, a, a);
    bmag1 = vfmaq_f64(bmag1, b, b);

    v1 = vld1q_f32(pVect1);
    pVect1 += 4;
    v2 = vld1q_f32(pVect2);
    pVect2 += 4;
    a = vcvt_f64_f32(vget_low_f32(v1));
    b = vcvt_f64_f32(vget_low_f32(v2));
    dot2 = vfmaq_f64(dot2, a, b);
    amag2 = vfmaq_f64(amag2, a, a);
    bmag2 = vfmaq_f64(bmag2, b, b);
    a = vcvt_high_f64_f32(v1);
    b = vcvt_high_f64_f32(v2);
    dot2 = vfmaq_f64(dot2, a, b);
    amag2 = vfmaq_f64(amag2, a, a);
    bmag2 = vfmaq_f64(bmag2, b, b);

    v1 = vld1q_f32(pVect1);
    pVect1 += 4;
    v2 = vld1q_f32(pVect2);
    pVect2 += 4;
    a = vcvt_f64_f32(vget_low_f32(v1));
    b = vcvt_f64_f32(vget_low_f32(v2));
    dot3 = vfmaq_f64(dot3, a, b);
    amag3 = vfmaq_f64(amag3, a, a);
    bmag3 = vfmaq_f64(bmag3, b, b);
    a = vcvt_high_f64_f32(v1);
    b = vcvt_high_f64_f32(v2);
    dot3 = vfmaq_f64(dot3, a, b);
    amag3 = vfmaq_f64(amag3, a, a);
    bmag3 = vfmaq_f64(bmag3, b, b);
  }

  double dot =
      vaddvq_f64(vaddq_f64(vaddq_f64(dot0, dot1), vaddq_f64(dot2, dot3)));
  double aMag =
      vaddvq_f64(vaddq_f64(vaddq_f64(amag0, amag1), vaddq_f64(amag2, amag3)));
  double bMag =
      vaddvq_f64(vaddq_f64(vaddq_f64(bmag0, bmag1), vaddq_f64(bmag2, bmag3)));

  const f32 *pEnd2 = pVect1 + (qty - (qty16 << 4));
  while (pVect1 < pEnd2) {
    dot += (double)*pVect1 * (double)*pVect2;
    aMag += (double)*pVect1 * (double)*pVect1;
    bMag += (double)*pVect2 * (double)*pVect2;
    pVect1++;
    pVect2++;
  }

  // Handle zero vectors: return max distance (1.0) to avoid division by zero
  if (aMag == 0 || bMag == 0) {
    return 1.0f;
  }
  return 1 - (dot / (sqrt(aMag) * sqrt(bMag)));
}

// asg017/sqlite-vec's cosine_int8_neon, with distance_cosine_int8's zero
// vector case. Products of int8 elements are summed exactly: a 32-bit lane
// holds one pass's products, but 131,072 squares of -128 overflow a 32-bit
// sum, so each pass's lanes are added into 64-bit lanes, as in
// l2_sqr_int8_neon.
static f32 cosine_int8_neon(const void *pA, const void *pB, const void *pD) {
  const i8 *a = (const i8 *)pA;
  const i8 *b = (const i8 *)pB;
  size_t d = *((const size_t *)pD);
  const i8 *aEnd = a + d;

  int64x2_t dot_acc = vdupq_n_s64(0);
  int64x2_t aMag_acc = vdupq_n_s64(0);
  int64x2_t bMag_acc = vdupq_n_s64(0);

  while (a < aEnd - 31) {
    int32x4_t dot_acc1 = vdupq_n_s32(0);
    int32x4_t dot_acc2 = vdupq_n_s32(0);
    int32x4_t aMag_acc1 = vdupq_n_s32(0);
    int32x4_t aMag_acc2 = vdupq_n_s32(0);
    int32x4_t bMag_acc1 = vdupq_n_s32(0);
    int32x4_t bMag_acc2 = vdupq_n_s32(0);
    int8x16_t va1 = vld1q_s8(a);
    int8x16_t vb1 = vld1q_s8(b);
    int16x8_t a1_lo = vmovl_s8(vget_low_s8(va1));
    int16x8_t a1_hi = vmovl_s8(vget_high_s8(va1));
    int16x8_t b1_lo = vmovl_s8(vget_low_s8(vb1));
    int16x8_t b1_hi = vmovl_s8(vget_high_s8(vb1));

    dot_acc1 = vmlal_s16(dot_acc1, vget_low_s16(a1_lo), vget_low_s16(b1_lo));
    dot_acc1 = vmlal_s16(dot_acc1, vget_high_s16(a1_lo), vget_high_s16(b1_lo));
    dot_acc2 = vmlal_s16(dot_acc2, vget_low_s16(a1_hi), vget_low_s16(b1_hi));
    dot_acc2 = vmlal_s16(dot_acc2, vget_high_s16(a1_hi), vget_high_s16(b1_hi));

    aMag_acc1 = vmlal_s16(aMag_acc1, vget_low_s16(a1_lo), vget_low_s16(a1_lo));
    aMag_acc1 =
        vmlal_s16(aMag_acc1, vget_high_s16(a1_lo), vget_high_s16(a1_lo));
    aMag_acc2 = vmlal_s16(aMag_acc2, vget_low_s16(a1_hi), vget_low_s16(a1_hi));
    aMag_acc2 =
        vmlal_s16(aMag_acc2, vget_high_s16(a1_hi), vget_high_s16(a1_hi));

    bMag_acc1 = vmlal_s16(bMag_acc1, vget_low_s16(b1_lo), vget_low_s16(b1_lo));
    bMag_acc1 =
        vmlal_s16(bMag_acc1, vget_high_s16(b1_lo), vget_high_s16(b1_lo));
    bMag_acc2 = vmlal_s16(bMag_acc2, vget_low_s16(b1_hi), vget_low_s16(b1_hi));
    bMag_acc2 =
        vmlal_s16(bMag_acc2, vget_high_s16(b1_hi), vget_high_s16(b1_hi));

    int8x16_t va2 = vld1q_s8(a + 16);
    int8x16_t vb2 = vld1q_s8(b + 16);
    int16x8_t a2_lo = vmovl_s8(vget_low_s8(va2));
    int16x8_t a2_hi = vmovl_s8(vget_high_s8(va2));
    int16x8_t b2_lo = vmovl_s8(vget_low_s8(vb2));
    int16x8_t b2_hi = vmovl_s8(vget_high_s8(vb2));

    dot_acc1 = vmlal_s16(dot_acc1, vget_low_s16(a2_lo), vget_low_s16(b2_lo));
    dot_acc1 = vmlal_s16(dot_acc1, vget_high_s16(a2_lo), vget_high_s16(b2_lo));
    dot_acc2 = vmlal_s16(dot_acc2, vget_low_s16(a2_hi), vget_low_s16(b2_hi));
    dot_acc2 = vmlal_s16(dot_acc2, vget_high_s16(a2_hi), vget_high_s16(b2_hi));

    aMag_acc1 = vmlal_s16(aMag_acc1, vget_low_s16(a2_lo), vget_low_s16(a2_lo));
    aMag_acc1 =
        vmlal_s16(aMag_acc1, vget_high_s16(a2_lo), vget_high_s16(a2_lo));
    aMag_acc2 = vmlal_s16(aMag_acc2, vget_low_s16(a2_hi), vget_low_s16(a2_hi));
    aMag_acc2 =
        vmlal_s16(aMag_acc2, vget_high_s16(a2_hi), vget_high_s16(a2_hi));

    bMag_acc1 = vmlal_s16(bMag_acc1, vget_low_s16(b2_lo), vget_low_s16(b2_lo));
    bMag_acc1 =
        vmlal_s16(bMag_acc1, vget_high_s16(b2_lo), vget_high_s16(b2_lo));
    bMag_acc2 = vmlal_s16(bMag_acc2, vget_low_s16(b2_hi), vget_low_s16(b2_hi));
    bMag_acc2 =
        vmlal_s16(bMag_acc2, vget_high_s16(b2_hi), vget_high_s16(b2_hi));

    dot_acc = vpadalq_s32(dot_acc, vaddq_s32(dot_acc1, dot_acc2));
    aMag_acc = vpadalq_s32(aMag_acc, vaddq_s32(aMag_acc1, aMag_acc2));
    bMag_acc = vpadalq_s32(bMag_acc, vaddq_s32(bMag_acc1, bMag_acc2));
    a += 32;
    b += 32;
  }

  while (a < aEnd - 15) {
    int32x4_t dot_acc1 = vdupq_n_s32(0);
    int32x4_t aMag_acc1 = vdupq_n_s32(0);
    int32x4_t bMag_acc1 = vdupq_n_s32(0);
    int8x16_t va = vld1q_s8(a);
    int8x16_t vb = vld1q_s8(b);
    int16x8_t a_lo = vmovl_s8(vget_low_s8(va));
    int16x8_t a_hi = vmovl_s8(vget_high_s8(va));
    int16x8_t b_lo = vmovl_s8(vget_low_s8(vb));
    int16x8_t b_hi = vmovl_s8(vget_high_s8(vb));

    dot_acc1 = vmlal_s16(dot_acc1, vget_low_s16(a_lo), vget_low_s16(b_lo));
    dot_acc1 = vmlal_s16(dot_acc1, vget_high_s16(a_lo), vget_high_s16(b_lo));
    dot_acc1 = vmlal_s16(dot_acc1, vget_low_s16(a_hi), vget_low_s16(b_hi));
    dot_acc1 = vmlal_s16(dot_acc1, vget_high_s16(a_hi), vget_high_s16(b_hi));

    aMag_acc1 = vmlal_s16(aMag_acc1, vget_low_s16(a_lo), vget_low_s16(a_lo));
    aMag_acc1 = vmlal_s16(aMag_acc1, vget_high_s16(a_lo), vget_high_s16(a_lo));
    aMag_acc1 = vmlal_s16(aMag_acc1, vget_low_s16(a_hi), vget_low_s16(a_hi));
    aMag_acc1 = vmlal_s16(aMag_acc1, vget_high_s16(a_hi), vget_high_s16(a_hi));

    bMag_acc1 = vmlal_s16(bMag_acc1, vget_low_s16(b_lo), vget_low_s16(b_lo));
    bMag_acc1 = vmlal_s16(bMag_acc1, vget_high_s16(b_lo), vget_high_s16(b_lo));
    bMag_acc1 = vmlal_s16(bMag_acc1, vget_low_s16(b_hi), vget_low_s16(b_hi));
    bMag_acc1 = vmlal_s16(bMag_acc1, vget_high_s16(b_hi), vget_high_s16(b_hi));

    dot_acc = vpadalq_s32(dot_acc, dot_acc1);
    aMag_acc = vpadalq_s32(aMag_acc, aMag_acc1);
    bMag_acc = vpadalq_s32(bMag_acc, bMag_acc1);
    a += 16;
    b += 16;
  }

  i64 dot = vaddvq_s64(dot_acc);
  i64 aMag = vaddvq_s64(aMag_acc);
  i64 bMag = vaddvq_s64(bMag_acc);

  while (a < aEnd) {
    dot += (i32)*a * (i32)*b;
    aMag += (i32)*a * (i32)*a;
    bMag += (i32)*b * (i32)*b;
    a++;
    b++;
  }

  // Handle zero vectors: return max distance (1.0) to avoid division by zero
  if (aMag == 0 || bMag == 0) {
    return 1.0f;
  }
  return 1.0f - ((f32)dot / (sqrtf((f32)aMag) * sqrtf((f32)bMag)));
}
#endif

static f32 l2_sqr_float(const void *pVect1v, const void *pVect2v,
                        const void *qty_ptr) {
  f32 *pVect1 = (f32 *)pVect1v;
  f32 *pVect2 = (f32 *)pVect2v;
  size_t qty = *((size_t *)qty_ptr);

  f32 res = 0;
  for (size_t i = 0; i < qty; i++) {
    f32 t = *pVect1 - *pVect2;
    pVect1++;
    pVect2++;
    res += t * t;
  }
  return sqrtf(res);
}

static f32 l2_sqr_int8(const void *pA, const void *pB, const void *pD) {
  i8 *a = (i8 *)pA;
  i8 *b = (i8 *)pB;
  size_t d = *((size_t *)pD);

  f32 res = 0;
  for (size_t i = 0; i < d; i++) {
    f32 t = *a - *b;
    a++;
    b++;
    res += t * t;
  }
  return sqrtf(res);
}

static f32 distance_l2_sqr_float(const void *a, const void *b, const void *d) {
#ifdef SQLITE_VEC_ENABLE_NEON
  if ((*(const size_t *)d) > 16) {
    return l2_sqr_float_neon(a, b, d);
  }
#endif
#ifdef SQLITE_VEC_ENABLE_AVX
  if (((*(const size_t *)d) % 16 == 0)) {
    return l2_sqr_float_avx(a, b, d);
  }
#endif
  return l2_sqr_float(a, b, d);
}

static f32 distance_l2_sqr_int8(const void *a, const void *b, const void *d) {
#ifdef SQLITE_VEC_ENABLE_NEON
  if ((*(const size_t *)d) > 7) {
    return l2_sqr_int8_neon(a, b, d);
  }
#endif
  return l2_sqr_int8(a, b, d);
}

static i32 l1_int8(const void *pA, const void *pB, const void *pD) {
  i8 *a = (i8 *)pA;
  i8 *b = (i8 *)pB;
  size_t d = *((size_t *)pD);

  i32 res = 0;
  for (size_t i = 0; i < d; i++) {
    res += abs(*a - *b);
    a++;
    b++;
  }

  return res;
}

static i32 distance_l1_int8(const void *a, const void *b, const void *d) {
#ifdef SQLITE_VEC_ENABLE_NEON
  if ((*(const size_t *)d) > 15) {
    return l1_int8_neon(a, b, d);
  }
#endif
  return l1_int8(a, b, d);
}

static double l1_f32(const void *pA, const void *pB, const void *pD) {
  f32 *a = (f32 *)pA;
  f32 *b = (f32 *)pB;
  size_t d = *((size_t *)pD);

  double res = 0;
  for (size_t i = 0; i < d; i++) {
    res += fabs((double)*a - (double)*b);
    a++;
    b++;
  }

  return res;
}

static double distance_l1_f32(const void *a, const void *b, const void *d) {
#ifdef SQLITE_VEC_ENABLE_NEON
  if ((*(const size_t *)d) > 3) {
    return l1_f32_neon(a, b, d);
  }
#endif
  return l1_f32(a, b, d);
}

// https://github.com/facebookresearch/faiss/blob/77e2e79cd0a680adc343b9840dd865da724c579e/faiss/utils/hamming_distance/common.h#L34
static u8 hamdist_table[256] = {
    0, 1, 1, 2, 1, 2, 2, 3, 1, 2, 2, 3, 2, 3, 3, 4, 1, 2, 2, 3, 2, 3, 3, 4,
    2, 3, 3, 4, 3, 4, 4, 5, 1, 2, 2, 3, 2, 3, 3, 4, 2, 3, 3, 4, 3, 4, 4, 5,
    2, 3, 3, 4, 3, 4, 4, 5, 3, 4, 4, 5, 4, 5, 5, 6, 1, 2, 2, 3, 2, 3, 3, 4,
    2, 3, 3, 4, 3, 4, 4, 5, 2, 3, 3, 4, 3, 4, 4, 5, 3, 4, 4, 5, 4, 5, 5, 6,
    2, 3, 3, 4, 3, 4, 4, 5, 3, 4, 4, 5, 4, 5, 5, 6, 3, 4, 4, 5, 4, 5, 5, 6,
    4, 5, 5, 6, 5, 6, 6, 7, 1, 2, 2, 3, 2, 3, 3, 4, 2, 3, 3, 4, 3, 4, 4, 5,
    2, 3, 3, 4, 3, 4, 4, 5, 3, 4, 4, 5, 4, 5, 5, 6, 2, 3, 3, 4, 3, 4, 4, 5,
    3, 4, 4, 5, 4, 5, 5, 6, 3, 4, 4, 5, 4, 5, 5, 6, 4, 5, 5, 6, 5, 6, 6, 7,
    2, 3, 3, 4, 3, 4, 4, 5, 3, 4, 4, 5, 4, 5, 5, 6, 3, 4, 4, 5, 4, 5, 5, 6,
    4, 5, 5, 6, 5, 6, 6, 7, 3, 4, 4, 5, 4, 5, 5, 6, 4, 5, 5, 6, 5, 6, 6, 7,
    4, 5, 5, 6, 5, 6, 6, 7, 5, 6, 6, 7, 6, 7, 7, 8};

// MSVC-compatible __builtin_popcountl - must be defined before first use
#ifdef _MSC_VER
#if !defined(__clang__) && (defined(_M_ARM) || defined(_M_ARM64))
// From
// https://github.com/ngtcp2/ngtcp2/blob/b64f1e77b5e0d880b93d31f474147fae4a1d17cc/lib/ngtcp2_ringbuf.c,
// line 34-43
static unsigned int __builtin_popcountl(u64 x) {
  unsigned int c = 0;
  for (; x; ++c) {
    x &= x - 1;
  }
  return c;
}
#else
#include <intrin.h>
#ifdef _WIN64
#define __builtin_popcountl __popcnt64
#else
static unsigned int __builtin_popcountl(u64 n) {
  return __popcnt((u32)n) + __popcnt((u32)(n >> 32));
}
#endif
#endif
#endif

static f32 distance_cosine_bit_u64(u64 *a, u64 *b, size_t n) {
  f32 dot = 0;
  f32 aMag = 0;
  f32 bMag = 0;

  for (size_t i = 0; i < n; i++) {
    dot += __builtin_popcountl(a[i] & b[i]);
    aMag += __builtin_popcountl(a[i]);
    bMag += __builtin_popcountl(b[i]);
  }

  // Handle zero vectors: return max distance (1.0) to avoid division by zero
  if (aMag == 0 || bMag == 0) {
    return 1.0f;
  }
  return 1 - (dot / (sqrtf(aMag) * sqrtf(bMag)));
}

static f32 distance_cosine_bit_u8(u8 *a, u8 *b, size_t n) {
  f32 dot = 0;
  f32 aMag = 0;
  f32 bMag = 0;

  for (size_t i = 0; i < n; i++) {
    dot += hamdist_table[a[i] & b[i]];
    aMag += hamdist_table[a[i]];
    bMag += hamdist_table[b[i]];
  }

  // Handle zero vectors: return max distance (1.0) to avoid division by zero
  if (aMag == 0 || bMag == 0) {
    return 1.0f;
  }
  return 1 - (dot / (sqrtf(aMag) * sqrtf(bMag)));
}

static f32 distance_cosine_bit(const void *pA, const void *pB, const void *pD) {
  size_t dim = *((size_t *)pD);

  if ((dim % 64) == 0) {
    return distance_cosine_bit_u64((u64 *)pA, (u64 *)pB, dim / 8 / CHAR_BIT);
  }
  return distance_cosine_bit_u8((u8 *)pA, (u8 *)pB, dim / CHAR_BIT);
}

static f32 distance_cosine_float(const void *pVect1v, const void *pVect2v,
                                 const void *qty_ptr) {
#ifdef SQLITE_VEC_ENABLE_NEON
  if ((*(const size_t *)qty_ptr) > 16) {
    return cosine_float_neon(pVect1v, pVect2v, qty_ptr);
  }
#endif
  f32 *pVect1 = (f32 *)pVect1v;
  f32 *pVect2 = (f32 *)pVect2v;
  size_t qty = *((size_t *)qty_ptr);

  // Accumulate in double: the square of a small (or large) f32 element
  // underflows (or overflows) f32, which made the magnitude 0 (or Inf) and
  // the distance +-Inf, NaN or plain wrong for nonzero finite vectors. Every
  // f32 product is representable in double.
  double dot = 0;
  double aMag = 0;
  double bMag = 0;
  for (size_t i = 0; i < qty; i++) {
    dot += (double)*pVect1 * (double)*pVect2;
    aMag += (double)*pVect1 * (double)*pVect1;
    bMag += (double)*pVect2 * (double)*pVect2;
    pVect1++;
    pVect2++;
  }
  // Handle zero vectors: return max distance (1.0) to avoid division by zero
  if (aMag == 0 || bMag == 0) {
    return 1.0f;
  }
  return 1 - (dot / (sqrt(aMag) * sqrt(bMag)));
}
static f32 distance_cosine_int8(const void *pA, const void *pB,
                                const void *pD) {
#ifdef SQLITE_VEC_ENABLE_NEON
  if ((*(const size_t *)pD) > 15) {
    return cosine_int8_neon(pA, pB, pD);
  }
#endif
  i8 *a = (i8 *)pA;
  i8 *b = (i8 *)pB;
  size_t d = *((size_t *)pD);

  f32 dot = 0;
  f32 aMag = 0;
  f32 bMag = 0;
  for (size_t i = 0; i < d; i++) {
    dot += *a * *b;
    aMag += *a * *a;
    bMag += *b * *b;
    a++;
    b++;
  }
  // Handle zero vectors: return max distance (1.0) to avoid division by zero
  if (aMag == 0 || bMag == 0) {
    return 1.0f;
  }
  return 1 - (dot / (sqrtf(aMag) * sqrtf(bMag)));
}

static f32 distance_hamming_u8(u8 *a, u8 *b, size_t n) {
  int same = 0;
  for (unsigned long i = 0; i < n; i++) {
    same += hamdist_table[a[i] ^ b[i]];
  }
  return (f32)same;
}

#ifdef SQLITE_VEC_ENABLE_NEON
static f32 distance_hamming_neon(const u8 *a, const u8 *b, size_t n_bytes) {
  const u8 *pEnd = a + n_bytes;

  uint32x4_t acc1 = vdupq_n_u32(0);
  uint32x4_t acc2 = vdupq_n_u32(0);
  uint32x4_t acc3 = vdupq_n_u32(0);
  uint32x4_t acc4 = vdupq_n_u32(0);

  while (pEnd - a >= 64) {
    uint8x16_t v1 = vld1q_u8(a);
    uint8x16_t v2 = vld1q_u8(b);
    acc1 = vaddq_u32(acc1, vpaddlq_u16(vpaddlq_u8(vcntq_u8(veorq_u8(v1, v2)))));

    v1 = vld1q_u8(a + 16);
    v2 = vld1q_u8(b + 16);
    acc2 = vaddq_u32(acc2, vpaddlq_u16(vpaddlq_u8(vcntq_u8(veorq_u8(v1, v2)))));

    v1 = vld1q_u8(a + 32);
    v2 = vld1q_u8(b + 32);
    acc3 = vaddq_u32(acc3, vpaddlq_u16(vpaddlq_u8(vcntq_u8(veorq_u8(v1, v2)))));

    v1 = vld1q_u8(a + 48);
    v2 = vld1q_u8(b + 48);
    acc4 = vaddq_u32(acc4, vpaddlq_u16(vpaddlq_u8(vcntq_u8(veorq_u8(v1, v2)))));

    a += 64;
    b += 64;
  }

  while (pEnd - a >= 16) {
    uint8x16_t v1 = vld1q_u8(a);
    uint8x16_t v2 = vld1q_u8(b);
    acc1 = vaddq_u32(acc1, vpaddlq_u16(vpaddlq_u8(vcntq_u8(veorq_u8(v1, v2)))));
    a += 16;
    b += 16;
  }

  acc1 = vaddq_u32(acc1, acc2);
  acc3 = vaddq_u32(acc3, acc4);
  acc1 = vaddq_u32(acc1, acc3);
  u32 sum = vaddvq_u32(acc1);

  while (a < pEnd) {
    sum += hamdist_table[*a ^ *b];
    a++;
    b++;
  }

  return (f32)sum;
}
#endif

static f32 distance_hamming_u64(const u8 *a, const u8 *b, size_t n) {
  int same = 0;
  for (unsigned long i = 0; i < n; i++) {
    // memcpy loads: the blob pointers may not be u64-aligned
    u64 va, vb;
    memcpy(&va, a + i * sizeof(u64), sizeof(u64));
    memcpy(&vb, b + i * sizeof(u64), sizeof(u64));
    same += __builtin_popcountl(va ^ vb);
  }
  return (f32)same;
}

/**
 * @brief Calculate the hamming distance between two bitvectors.
 *
 * @param a - first bitvector, MUST have d dimensions
 * @param b - second bitvector, MUST have d dimensions
 * @param d - pointer to size_t, MUST be divisible by CHAR_BIT
 * @return f32
 */
static f32 distance_hamming(const void *a, const void *b, const void *d) {
  size_t dimensions = *((size_t *)d);
  size_t n_bytes = dimensions / CHAR_BIT;

#ifdef SQLITE_VEC_ENABLE_NEON
  if (dimensions >= 128) {
    return distance_hamming_neon((const u8 *)a, (const u8 *)b, n_bytes);
  }
#endif

  if ((dimensions % 64) == 0) {
    return distance_hamming_u64((const u8 *)a, (const u8 *)b,
                                n_bytes / sizeof(u64));
  }
  return distance_hamming_u8((u8 *)a, (u8 *)b, n_bytes);
}

// from SQLite source:
// https://github.com/sqlite/sqlite/blob/a509a90958ddb234d1785ed7801880ccb18b497e/src/json.c#L153
static const char vecJsonIsSpaceX[] = {
    0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0,
    0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
    0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
    0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
    0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
    0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,

    0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
    0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
    0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
    0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
    0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
    0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
};

#define vecJsonIsspace(x) (vecJsonIsSpaceX[(unsigned char)x])

typedef void (*vector_cleanup)(void *p);

void vector_cleanup_noop(void *_) { UNUSED_PARAMETER(_); }

#define JSON_SUBTYPE 74

void vtab_set_error(sqlite3_vtab *pVTab, const char *zFormat, ...) {
  va_list args;
  sqlite3_free(pVTab->zErrMsg);
  va_start(args, zFormat);
  pVTab->zErrMsg = sqlite3_vmprintf(zFormat, args);
  va_end(args);
}
struct Array {
  size_t element_size;
  size_t length;
  size_t capacity;
  void *z;
};

/**
 * @brief Initial an array with the given element size and capacity.
 *
 * @param array
 * @param element_size
 * @param init_capacity
 * @return SQLITE_OK on success, error code on failure. Only error is
 * SQLITE_NOMEM
 */
int array_init(struct Array *array, size_t element_size, size_t init_capacity) {
  int sz = element_size * init_capacity;
  void *z = sqlite3_malloc(sz);
  if (!z) {
    return SQLITE_NOMEM;
  }
  memset(z, 0, sz);

  array->element_size = element_size;
  array->length = 0;
  array->capacity = init_capacity;
  array->z = z;
  return SQLITE_OK;
}

int array_append(struct Array *array, const void *element) {
  if (array->length == array->capacity) {
    size_t new_capacity = array->capacity * 2 + 100;
    void *z = sqlite3_realloc64(array->z, array->element_size * new_capacity);
    if (z) {
      array->capacity = new_capacity;
      array->z = z;
    } else {
      return SQLITE_NOMEM;
    }
  }
  memcpy(&((unsigned char *)array->z)[array->length * array->element_size],
         element, array->element_size);
  array->length++;
  return SQLITE_OK;
}

void array_cleanup(struct Array *array) {
  if (!array)
    return;
  array->element_size = 0;
  array->length = 0;
  array->capacity = 0;
  sqlite3_free(array->z);
  array->z = NULL;
}

char *vector_subtype_name(int subtype) {
  switch (subtype) {
  case SQLITE_VEC_ELEMENT_TYPE_FLOAT32:
    return "float32";
  case SQLITE_VEC_ELEMENT_TYPE_INT8:
    return "int8";
  case SQLITE_VEC_ELEMENT_TYPE_BIT:
    return "bit";
  }
  return "";
}
char *type_name(int type) {
  switch (type) {
  case SQLITE_INTEGER:
    return "INTEGER";
  case SQLITE_BLOB:
    return "BLOB";
  case SQLITE_TEXT:
    return "TEXT";
  case SQLITE_FLOAT:
    return "FLOAT";
  case SQLITE_NULL:
    return "NULL";
  }
  return "";
}

typedef void (*fvec_cleanup)(void *vector);

static int fvec_from_value(sqlite3_value *value, f32 **vector,
                           size_t *dimensions, fvec_cleanup *cleanup,
                           char **pzErr) {
  int value_type = sqlite3_value_type(value);

  if (value_type == SQLITE_BLOB) {
    const void *blob = sqlite3_value_blob(value);
    int bytes = sqlite3_value_bytes(value);
    if (bytes == 0) {
      *pzErr = sqlite3_mprintf("zero-length vectors are not supported.");
      return SQLITE_ERROR;
    }
    if ((bytes % sizeof(f32)) != 0) {
      *pzErr = sqlite3_mprintf("invalid float32 vector BLOB length. Must be "
                               "divisible by %d, found %d",
                               sizeof(f32), bytes);
      return SQLITE_ERROR;
    }
    // copy rather than alias the blob: it may not be f32-aligned
    f32 *buf = sqlite3_malloc(bytes);
    if (!buf) {
      *pzErr = sqlite3_mprintf("out of memory");
      return SQLITE_NOMEM;
    }
    memcpy(buf, blob, bytes);
    size_t n = bytes / sizeof(f32);
    for (size_t i = 0; i < n; i++) {
      if (isnan(buf[i]) || isinf(buf[i])) {
        *pzErr = sqlite3_mprintf("invalid float32 vector: element %d is %s",
                                 (int)i, isnan(buf[i]) ? "NaN" : "Inf");
        sqlite3_free(buf);
        return SQLITE_ERROR;
      }
    }
    *vector = buf;
    *dimensions = n;
    *cleanup = sqlite3_free;
    return SQLITE_OK;
  }

  if (value_type == SQLITE_TEXT) {
    const char *source = (const char *)sqlite3_value_text(value);
    int source_len = sqlite3_value_bytes(value);
    if (source_len == 0) {
      *pzErr = sqlite3_mprintf("zero-length vectors are not supported.");
      return SQLITE_ERROR;
    }
    int i = 0;

    struct Array x;
    int rc = array_init(&x, sizeof(f32), ceil(source_len / 2.0));
    if (rc != SQLITE_OK) {
      return rc;
    }

    // advance leading whitespace to first '['
    while (i < source_len) {
      if (vecJsonIsspace(source[i])) {
        i++;
        continue;
      }
      if (source[i] == '[') {
        break;
      }

      *pzErr = sqlite3_mprintf(
          "JSON array parsing error: Input does not start with '['");
      array_cleanup(&x);
      return SQLITE_ERROR;
    }
    if (source[i] != '[') {
      *pzErr = sqlite3_mprintf(
          "JSON array parsing error: Input does not start with '['");
      array_cleanup(&x);
      return SQLITE_ERROR;
    }
    int offset = i + 1;

    while (offset < source_len) {
      char *ptr = (char *)&source[offset];
      char *endptr;

      errno = 0;
      double result = strtod_c(ptr, &endptr);
      if ((errno != 0 && result == 0) // some interval error?
          || (errno == ERANGE &&
              (result == HUGE_VAL || result == -HUGE_VAL)) // too big / smalls
      ) {
        sqlite3_free(x.z);
        *pzErr = sqlite3_mprintf("JSON parsing error");
        return SQLITE_ERROR;
      }

      if (endptr == ptr) {
        if (*ptr != ']') {
          sqlite3_free(x.z);
          *pzErr = sqlite3_mprintf("JSON parsing error");
          return SQLITE_ERROR;
        }
        goto done;
      }

      f32 res = (f32)result;
      if (isnan(res) || isinf(res)) {
        sqlite3_free(x.z);
        *pzErr = sqlite3_mprintf("invalid float32 vector: element %d is %s",
                                 (int)x.length, isnan(res) ? "NaN" : "Inf");
        return SQLITE_ERROR;
      }
      array_append(&x, (const void *)&res);

      offset += (endptr - ptr);
      while (offset < source_len) {
        if (vecJsonIsspace(source[offset])) {
          offset++;
          continue;
        }
        if (source[offset] == ',') {
          offset++;
          continue;
        }
        if (source[offset] == ']')
          goto done;
        break;
      }
    }

  done:

    if (x.length > 0) {
      *vector = (f32 *)x.z;
      *dimensions = x.length;
      *cleanup = sqlite3_free;
      return SQLITE_OK;
    }
    sqlite3_free(x.z);
    *pzErr = sqlite3_mprintf("zero-length vectors are not supported.");
    return SQLITE_ERROR;
  }

  *pzErr = sqlite3_mprintf(
      "Input must have type BLOB (compact format) or TEXT (JSON), found %s",
      type_name(value_type));
  return SQLITE_ERROR;
}

static int bitvec_from_value(sqlite3_value *value, u8 **vector,
                             size_t *dimensions, vector_cleanup *cleanup,
                             char **pzErr) {
  int value_type = sqlite3_value_type(value);
  if (value_type == SQLITE_BLOB) {
    const void *blob = sqlite3_value_blob(value);
    int bytes = sqlite3_value_bytes(value);
    if (bytes == 0) {
      *pzErr = sqlite3_mprintf("zero-length vectors are not supported.");
      return SQLITE_ERROR;
    }
    *vector = (u8 *)blob;
    *dimensions = bytes * CHAR_BIT;
    *cleanup = vector_cleanup_noop;
    return SQLITE_OK;
  }
  *pzErr = sqlite3_mprintf("Unknown type for bitvector.");
  return SQLITE_ERROR;
}

static int int8_vec_from_value(sqlite3_value *value, i8 **vector,
                               size_t *dimensions, vector_cleanup *cleanup,
                               char **pzErr) {
  int value_type = sqlite3_value_type(value);
  if (value_type == SQLITE_BLOB) {
    const void *blob = sqlite3_value_blob(value);
    int bytes = sqlite3_value_bytes(value);
    if (bytes == 0) {
      *pzErr = sqlite3_mprintf("zero-length vectors are not supported.");
      return SQLITE_ERROR;
    }
    *vector = (i8 *)blob;
    *dimensions = bytes;
    *cleanup = vector_cleanup_noop;
    return SQLITE_OK;
  }

  if (value_type == SQLITE_TEXT) {
    const char *source = (const char *)sqlite3_value_text(value);
    int source_len = sqlite3_value_bytes(value);
    int i = 0;

    if (source_len == 0) {
      *pzErr = sqlite3_mprintf("zero-length vectors are not supported.");
      return SQLITE_ERROR;
    }

    struct Array x;
    int rc = array_init(&x, sizeof(i8), ceil(source_len / 2.0));
    if (rc != SQLITE_OK) {
      return rc;
    }

    // advance leading whitespace to first '['
    while (i < source_len) {
      if (vecJsonIsspace(source[i])) {
        i++;
        continue;
      }
      if (source[i] == '[') {
        break;
      }

      *pzErr = sqlite3_mprintf(
          "JSON array parsing error: Input does not start with '['");
      array_cleanup(&x);
      return SQLITE_ERROR;
    }
    if (source[i] != '[') {
      *pzErr = sqlite3_mprintf(
          "JSON array parsing error: Input does not start with '['");
      array_cleanup(&x);
      return SQLITE_ERROR;
    }
    int offset = i + 1;

    while (offset < source_len) {
      char *ptr = (char *)&source[offset];
      char *endptr;

      errno = 0;
      long result = strtol(ptr, &endptr, 10);
      if ((errno != 0 && result == 0) ||
          (errno == ERANGE && (result == LONG_MAX || result == LONG_MIN))) {
        sqlite3_free(x.z);
        *pzErr = sqlite3_mprintf("JSON parsing error");
        return SQLITE_ERROR;
      }

      if (endptr == ptr) {
        if (*ptr != ']') {
          sqlite3_free(x.z);
          *pzErr = sqlite3_mprintf("JSON parsing error");
          return SQLITE_ERROR;
        }
        goto done;
      }

      if (result < INT8_MIN || result > INT8_MAX) {
        sqlite3_free(x.z);
        *pzErr =
            sqlite3_mprintf("JSON parsing error: value out of range for int8");
        return SQLITE_ERROR;
      }

      i8 res = (i8)result;
      array_append(&x, (const void *)&res);

      offset += (endptr - ptr);
      while (offset < source_len) {
        if (vecJsonIsspace(source[offset])) {
          offset++;
          continue;
        }
        if (source[offset] == ',') {
          offset++;
          continue;
        }
        if (source[offset] == ']')
          goto done;
        break;
      }
    }

  done:

    if (x.length > 0) {
      *vector = (i8 *)x.z;
      *dimensions = x.length;
      *cleanup = (vector_cleanup)sqlite3_free;
      return SQLITE_OK;
    }
    sqlite3_free(x.z);
    *pzErr = sqlite3_mprintf("zero-length vectors are not supported.");
    return SQLITE_ERROR;
  }

  *pzErr = sqlite3_mprintf("Unknown type for int8 vector.");
  return SQLITE_ERROR;
}

/**
 * @brief Extract a vector from a sqlite3_value. Can be a float32, int8, or bit
 * vector.
 *
 * @param value: the sqlite3_value to read from.
 * @param vector: Output pointer to vector data.
 * @param dimensions: Output number of dimensions
 * @param dimensions: Output vector element type
 * @param cleanup
 * @param pzErrorMessage
 * @return int SQLITE_OK on success, error code otherwise
 */
int vector_from_value(sqlite3_value *value, void **vector, size_t *dimensions,
                      enum VectorElementType *element_type,
                      vector_cleanup *cleanup, char **pzErrorMessage) {
  int subtype = sqlite3_value_subtype(value);
  if (!subtype || (subtype == SQLITE_VEC_ELEMENT_TYPE_FLOAT32) ||
      (subtype == JSON_SUBTYPE)) {
    int rc = fvec_from_value(value, (f32 **)vector, dimensions, cleanup,
                             pzErrorMessage);
    if (rc == SQLITE_OK) {
      *element_type = SQLITE_VEC_ELEMENT_TYPE_FLOAT32;
    }
    return rc;
  }

  if (subtype == SQLITE_VEC_ELEMENT_TYPE_BIT) {
    int rc = bitvec_from_value(value, (u8 **)vector, dimensions, cleanup,
                               pzErrorMessage);
    if (rc == SQLITE_OK) {
      *element_type = SQLITE_VEC_ELEMENT_TYPE_BIT;
    }
    return rc;
  }
  if (subtype == SQLITE_VEC_ELEMENT_TYPE_INT8) {
    int rc = int8_vec_from_value(value, (i8 **)vector, dimensions, cleanup,
                                 pzErrorMessage);
    if (rc == SQLITE_OK) {
      *element_type = SQLITE_VEC_ELEMENT_TYPE_INT8;
    }
    return rc;
  }
  *pzErrorMessage = sqlite3_mprintf("Unknown subtype: %d", subtype);
  return SQLITE_ERROR;
}

int ensure_vector_match(sqlite3_value *aValue, sqlite3_value *bValue, void **a,
                        void **b, enum VectorElementType *element_type,
                        size_t *dimensions, vector_cleanup *outACleanup,
                        vector_cleanup *outBCleanup, char **outError) {
  int rc;
  enum VectorElementType aType, bType;
  size_t aDims, bDims;
  char *error = NULL;
  vector_cleanup aCleanup, bCleanup;

  rc = vector_from_value(aValue, a, &aDims, &aType, &aCleanup, &error);
  if (rc != SQLITE_OK) {
    *outError = sqlite3_mprintf("Error reading 1st vector: %s", error);
    sqlite3_free(error);
    return SQLITE_ERROR;
  }

  rc = vector_from_value(bValue, b, &bDims, &bType, &bCleanup, &error);
  if (rc != SQLITE_OK) {
    *outError = sqlite3_mprintf("Error reading 2nd vector: %s", error);
    sqlite3_free(error);
    aCleanup(*a);
    return SQLITE_ERROR;
  }

  if (aType != bType) {
    *outError =
        sqlite3_mprintf("Vector type mistmatch. First vector has type %s, "
                        "while the second has type %s.",
                        vector_subtype_name(aType), vector_subtype_name(bType));
    aCleanup(*a);
    bCleanup(*b);
    return SQLITE_ERROR;
  }
  if (aDims != bDims) {
    *outError = sqlite3_mprintf(
        "Vector dimension mistmatch. First vector has %ld dimensions, "
        "while the second has %ld dimensions.",
        aDims, bDims);
    aCleanup(*a);
    bCleanup(*b);
    return SQLITE_ERROR;
  }
  *element_type = aType;
  *dimensions = aDims;
  *outACleanup = aCleanup;
  *outBCleanup = bCleanup;
  return SQLITE_OK;
}

static int _cmp(const void *a, const void *b) {
  i64 x = *(i64 *)a;
  i64 y = *(i64 *)b;
  return (x > y) - (x < y);
}

struct VecNpyFile {
  char *path;
  size_t pathLength;
};
#define SQLITE_VEC_NPY_FILE_NAME "vec0-npy-file"

#ifndef SQLITE_VEC_OMIT_FS
static void vec_npy_file(sqlite3_context *context, int argc,
                         sqlite3_value **argv) {
  assert(argc == 1);
  char *path = (char *)sqlite3_value_text(argv[0]);
  size_t pathLength = sqlite3_value_bytes(argv[0]);
  struct VecNpyFile *f;

  f = sqlite3_malloc(sizeof(*f));
  if (!f) {
    sqlite3_result_error_nomem(context);
    return;
  }
  memset(f, 0, sizeof(*f));

  f->path = path;
  f->pathLength = pathLength;
  sqlite3_result_pointer(context, f, SQLITE_VEC_NPY_FILE_NAME, sqlite3_free);
}
#endif

#pragma region scalar functions
static void vec_f32(sqlite3_context *context, int argc, sqlite3_value **argv) {
  assert(argc == 1);
  int rc;
  f32 *vector = NULL;
  size_t dimensions;
  fvec_cleanup cleanup;
  char *errmsg;
  rc = fvec_from_value(argv[0], &vector, &dimensions, &cleanup, &errmsg);
  if (rc != SQLITE_OK) {
    sqlite3_result_error(context, errmsg, -1);
    sqlite3_free(errmsg);
    return;
  }
  sqlite3_result_blob(context, vector, dimensions * sizeof(f32),
                      (void (*)(void *))cleanup);
  sqlite3_result_subtype(context, SQLITE_VEC_ELEMENT_TYPE_FLOAT32);
}

static void vec_bit(sqlite3_context *context, int argc, sqlite3_value **argv) {
  assert(argc == 1);
  int rc;
  u8 *vector;
  size_t dimensions;
  vector_cleanup cleanup;
  char *errmsg;
  rc = bitvec_from_value(argv[0], &vector, &dimensions, &cleanup, &errmsg);
  if (rc != SQLITE_OK) {
    sqlite3_result_error(context, errmsg, -1);
    sqlite3_free(errmsg);
    return;
  }
  sqlite3_result_blob(context, vector, dimensions / CHAR_BIT, SQLITE_TRANSIENT);
  sqlite3_result_subtype(context, SQLITE_VEC_ELEMENT_TYPE_BIT);
  cleanup(vector);
}
static void vec_int8(sqlite3_context *context, int argc, sqlite3_value **argv) {
  assert(argc == 1);
  int rc;
  i8 *vector;
  size_t dimensions;
  vector_cleanup cleanup;
  char *errmsg;
  rc = int8_vec_from_value(argv[0], &vector, &dimensions, &cleanup, &errmsg);
  if (rc != SQLITE_OK) {
    sqlite3_result_error(context, errmsg, -1);
    sqlite3_free(errmsg);
    return;
  }
  sqlite3_result_blob(context, vector, dimensions, SQLITE_TRANSIENT);
  sqlite3_result_subtype(context, SQLITE_VEC_ELEMENT_TYPE_INT8);
  cleanup(vector);
}

static void vec_length(sqlite3_context *context, int argc,
                       sqlite3_value **argv) {
  assert(argc == 1);
  int rc;
  void *vector;
  size_t dimensions;
  vector_cleanup cleanup;
  char *errmsg;
  enum VectorElementType elementType;
  rc = vector_from_value(argv[0], &vector, &dimensions, &elementType, &cleanup,
                         &errmsg);
  if (rc != SQLITE_OK) {
    sqlite3_result_error(context, errmsg, -1);
    sqlite3_free(errmsg);
    return;
  }
  sqlite3_result_int64(context, dimensions);
  cleanup(vector);
}

static void vec_distance_cosine(sqlite3_context *context, int argc,
                                sqlite3_value **argv) {
  assert(argc == 2);
  int rc;
  void *a = NULL, *b = NULL;
  size_t dimensions;
  vector_cleanup aCleanup, bCleanup;
  char *error;
  enum VectorElementType elementType;
  rc = ensure_vector_match(argv[0], argv[1], &a, &b, &elementType, &dimensions,
                           &aCleanup, &bCleanup, &error);
  if (rc != SQLITE_OK) {
    sqlite3_result_error(context, error, -1);
    sqlite3_free(error);
    return;
  }

  switch (elementType) {
  case SQLITE_VEC_ELEMENT_TYPE_BIT: {
    f32 result = distance_cosine_bit(a, b, &dimensions);
    sqlite3_result_double(context, result);
    goto finish;
  }
  case SQLITE_VEC_ELEMENT_TYPE_FLOAT32: {
    f32 result = distance_cosine_float(a, b, &dimensions);
    sqlite3_result_double(context, result);
    goto finish;
  }
  case SQLITE_VEC_ELEMENT_TYPE_INT8: {
    f32 result = distance_cosine_int8(a, b, &dimensions);
    sqlite3_result_double(context, result);
    goto finish;
  }
  }

finish:
  aCleanup(a);
  bCleanup(b);
  return;
}

static void vec_distance_l2(sqlite3_context *context, int argc,
                            sqlite3_value **argv) {
  assert(argc == 2);
  int rc;
  void *a = NULL, *b = NULL;
  size_t dimensions;
  vector_cleanup aCleanup, bCleanup;
  char *error;
  enum VectorElementType elementType;
  rc = ensure_vector_match(argv[0], argv[1], &a, &b, &elementType, &dimensions,
                           &aCleanup, &bCleanup, &error);
  if (rc != SQLITE_OK) {
    sqlite3_result_error(context, error, -1);
    sqlite3_free(error);
    return;
  }

  switch (elementType) {
  case SQLITE_VEC_ELEMENT_TYPE_BIT: {
    sqlite3_result_error(
        context, "Cannot calculate L2 distance between two bitvectors.", -1);
    goto finish;
  }
  case SQLITE_VEC_ELEMENT_TYPE_FLOAT32: {
    f32 result = distance_l2_sqr_float(a, b, &dimensions);
    sqlite3_result_double(context, result);
    goto finish;
  }
  case SQLITE_VEC_ELEMENT_TYPE_INT8: {
    f32 result = distance_l2_sqr_int8(a, b, &dimensions);
    sqlite3_result_double(context, result);
    goto finish;
  }
  }

finish:
  aCleanup(a);
  bCleanup(b);
  return;
}

static void vec_distance_l1(sqlite3_context *context, int argc,
                            sqlite3_value **argv) {
  assert(argc == 2);
  int rc;
  void *a, *b;
  size_t dimensions;
  vector_cleanup aCleanup, bCleanup;
  char *error;
  enum VectorElementType elementType;
  rc = ensure_vector_match(argv[0], argv[1], &a, &b, &elementType, &dimensions,
                           &aCleanup, &bCleanup, &error);
  if (rc != SQLITE_OK) {
    sqlite3_result_error(context, error, -1);
    sqlite3_free(error);
    return;
  }

  switch (elementType) {
  case SQLITE_VEC_ELEMENT_TYPE_BIT: {
    sqlite3_result_error(
        context, "Cannot calculate L1 distance between two bitvectors.", -1);
    goto finish;
  }
  case SQLITE_VEC_ELEMENT_TYPE_FLOAT32: {
    double result = distance_l1_f32(a, b, &dimensions);
    sqlite3_result_double(context, result);
    goto finish;
  }
  case SQLITE_VEC_ELEMENT_TYPE_INT8: {
    i64 result = distance_l1_int8(a, b, &dimensions);
    sqlite3_result_int(context, result);
    goto finish;
  }
  }

finish:
  aCleanup(a);
  bCleanup(b);
  return;
}

static void vec_distance_hamming(sqlite3_context *context, int argc,
                                 sqlite3_value **argv) {
  assert(argc == 2);
  int rc;
  void *a = NULL, *b = NULL;
  size_t dimensions;
  vector_cleanup aCleanup, bCleanup;
  char *error;
  enum VectorElementType elementType;
  rc = ensure_vector_match(argv[0], argv[1], &a, &b, &elementType, &dimensions,
                           &aCleanup, &bCleanup, &error);
  if (rc != SQLITE_OK) {
    sqlite3_result_error(context, error, -1);
    sqlite3_free(error);
    return;
  }

  switch (elementType) {
  case SQLITE_VEC_ELEMENT_TYPE_BIT: {
    sqlite3_result_double(context, distance_hamming(a, b, &dimensions));
    goto finish;
  }
  case SQLITE_VEC_ELEMENT_TYPE_FLOAT32: {
    sqlite3_result_error(
        context,
        "Cannot calculate hamming distance between two float32 vectors.", -1);
    goto finish;
  }
  case SQLITE_VEC_ELEMENT_TYPE_INT8: {
    sqlite3_result_error(
        context, "Cannot calculate hamming distance between two int8 vectors.",
        -1);
    goto finish;
  }
  }

finish:
  aCleanup(a);
  bCleanup(b);
  return;
}

char *vec_type_name(enum VectorElementType elementType) {
  switch (elementType) {
  case SQLITE_VEC_ELEMENT_TYPE_FLOAT32:
    return "float32";
  case SQLITE_VEC_ELEMENT_TYPE_INT8:
    return "int8";
  case SQLITE_VEC_ELEMENT_TYPE_BIT:
    return "bit";
  }
  return "";
}

static void vec_type(sqlite3_context *context, int argc, sqlite3_value **argv) {
  assert(argc == 1);
  void *vector;
  size_t dimensions;
  vector_cleanup cleanup;
  char *pzError;
  enum VectorElementType elementType;
  int rc = vector_from_value(argv[0], &vector, &dimensions, &elementType,
                             &cleanup, &pzError);
  if (rc != SQLITE_OK) {
    sqlite3_result_error(context, pzError, -1);
    sqlite3_free(pzError);
    return;
  }
  sqlite3_result_text(context, vec_type_name(elementType), -1, SQLITE_STATIC);
  cleanup(vector);
}
static void vec_quantize_binary(sqlite3_context *context, int argc,
                                sqlite3_value **argv) {
  assert(argc == 1);
  void *vector;
  size_t dimensions;
  vector_cleanup vectorCleanup;
  char *pzError;
  enum VectorElementType elementType;
  int rc = vector_from_value(argv[0], &vector, &dimensions, &elementType,
                             &vectorCleanup, &pzError);
  if (rc != SQLITE_OK) {
    sqlite3_result_error(context, pzError, -1);
    sqlite3_free(pzError);
    return;
  }

  if (dimensions <= 0) {
    sqlite3_result_error(context, "Zero length vectors are not supported.", -1);
    goto cleanup;
    return;
  }
  if ((dimensions % CHAR_BIT) != 0) {
    sqlite3_result_error(
        context,
        "Binary quantization requires vectors with a length divisible by 8",
        -1);
    goto cleanup;
    return;
  }

  int sz = dimensions / CHAR_BIT;
  u8 *out = sqlite3_malloc(sz);
  if (!out) {
    sqlite3_result_error_code(context, SQLITE_NOMEM);
    goto cleanup;
    return;
  }
  memset(out, 0, sz);

  switch (elementType) {
  case SQLITE_VEC_ELEMENT_TYPE_FLOAT32: {

    for (size_t i = 0; i < dimensions; i++) {
      int res = ((f32 *)vector)[i] > 0.0;
      out[i / 8] |= (res << (i % 8));
    }
    break;
  }
  case SQLITE_VEC_ELEMENT_TYPE_INT8: {
    for (size_t i = 0; i < dimensions; i++) {
      int res = ((i8 *)vector)[i] > 0;
      out[i / 8] |= (res << (i % 8));
    }
    break;
  }
  case SQLITE_VEC_ELEMENT_TYPE_BIT: {
    sqlite3_result_error(context,
                         "Can only binary quantize float or int8 vectors", -1);
    sqlite3_free(out);
    return;
  }
  }
  sqlite3_result_blob(context, out, sz, sqlite3_free);
  sqlite3_result_subtype(context, SQLITE_VEC_ELEMENT_TYPE_BIT);

cleanup:
  vectorCleanup(vector);
}

static void vec_quantize_int8(sqlite3_context *context, int argc,
                              sqlite3_value **argv) {
  assert(argc == 2);
  f32 *srcVector;
  size_t dimensions;
  fvec_cleanup srcCleanup;
  char *err;
  i8 *out = NULL;
  int rc = fvec_from_value(argv[0], &srcVector, &dimensions, &srcCleanup, &err);
  if (rc != SQLITE_OK) {
    sqlite3_result_error(context, err, -1);
    sqlite3_free(err);
    return;
  }

  int sz = dimensions * sizeof(i8);
  out = sqlite3_malloc(sz);
  if (!out) {
    sqlite3_result_error_nomem(context);
    goto cleanup;
  }
  memset(out, 0, sz);

  if ((sqlite3_value_type(argv[1]) != SQLITE_TEXT) ||
      (sqlite3_value_bytes(argv[1]) != strlen("unit")) ||
      (sqlite3_stricmp((const char *)sqlite3_value_text(argv[1]), "unit") !=
       0)) {
    sqlite3_result_error(
        context, "2nd argument to vec_quantize_int8() must be 'unit'.", -1);
    sqlite3_free(out);
    goto cleanup;
  }
  f32 step = (1.0 - (-1.0)) / 255;
  for (size_t i = 0; i < dimensions; i++) {
    double val = ((srcVector[i] - (-1.0)) / step) - 128;
    if (!(val <= 127.0))
      val = 127.0; /* also clamps NaN */
    if (!(val >= -128.0))
      val = -128.0;
    out[i] = (i8)val;
  }

  sqlite3_result_blob(context, out, dimensions * sizeof(i8), sqlite3_free);
  sqlite3_result_subtype(context, SQLITE_VEC_ELEMENT_TYPE_INT8);

cleanup:
  srcCleanup(srcVector);
}

static void vec_add(sqlite3_context *context, int argc, sqlite3_value **argv) {
  assert(argc == 2);
  int rc;
  void *a = NULL, *b = NULL;
  size_t dimensions;
  vector_cleanup aCleanup, bCleanup;
  char *error;
  enum VectorElementType elementType;
  rc = ensure_vector_match(argv[0], argv[1], &a, &b, &elementType, &dimensions,
                           &aCleanup, &bCleanup, &error);
  if (rc != SQLITE_OK) {
    sqlite3_result_error(context, error, -1);
    sqlite3_free(error);
    return;
  }

  switch (elementType) {
  case SQLITE_VEC_ELEMENT_TYPE_BIT: {
    sqlite3_result_error(context, "Cannot add two bitvectors together.", -1);
    goto finish;
  }
  case SQLITE_VEC_ELEMENT_TYPE_FLOAT32: {
    size_t outSize = dimensions * sizeof(f32);
    f32 *out = sqlite3_malloc(outSize);
    if (!out) {
      sqlite3_result_error_nomem(context);
      goto finish;
    }
    memset(out, 0, outSize);
    for (size_t i = 0; i < dimensions; i++) {
      out[i] = ((f32 *)a)[i] + ((f32 *)b)[i];
    }
    sqlite3_result_blob(context, out, outSize, sqlite3_free);
    sqlite3_result_subtype(context, SQLITE_VEC_ELEMENT_TYPE_FLOAT32);
    goto finish;
  }
  case SQLITE_VEC_ELEMENT_TYPE_INT8: {
    size_t outSize = dimensions * sizeof(i8);
    i8 *out = sqlite3_malloc(outSize);
    if (!out) {
      sqlite3_result_error_nomem(context);
      goto finish;
    }
    memset(out, 0, outSize);
    for (size_t i = 0; i < dimensions; i++) {
      out[i] = ((i8 *)a)[i] + ((i8 *)b)[i];
    }
    sqlite3_result_blob(context, out, outSize, sqlite3_free);
    sqlite3_result_subtype(context, SQLITE_VEC_ELEMENT_TYPE_INT8);
    goto finish;
  }
  }
finish:
  aCleanup(a);
  bCleanup(b);
  return;
}
static void vec_sub(sqlite3_context *context, int argc, sqlite3_value **argv) {
  assert(argc == 2);
  int rc;
  void *a = NULL, *b = NULL;
  size_t dimensions;
  vector_cleanup aCleanup, bCleanup;
  char *error;
  enum VectorElementType elementType;
  rc = ensure_vector_match(argv[0], argv[1], &a, &b, &elementType, &dimensions,
                           &aCleanup, &bCleanup, &error);
  if (rc != SQLITE_OK) {
    sqlite3_result_error(context, error, -1);
    sqlite3_free(error);
    return;
  }

  switch (elementType) {
  case SQLITE_VEC_ELEMENT_TYPE_BIT: {
    sqlite3_result_error(context, "Cannot subtract two bitvectors together.",
                         -1);
    goto finish;
  }
  case SQLITE_VEC_ELEMENT_TYPE_FLOAT32: {
    size_t outSize = dimensions * sizeof(f32);
    f32 *out = sqlite3_malloc(outSize);
    if (!out) {
      sqlite3_result_error_nomem(context);
      goto finish;
    }
    memset(out, 0, outSize);
    for (size_t i = 0; i < dimensions; i++) {
      out[i] = ((f32 *)a)[i] - ((f32 *)b)[i];
    }
    sqlite3_result_blob(context, out, outSize, sqlite3_free);
    sqlite3_result_subtype(context, SQLITE_VEC_ELEMENT_TYPE_FLOAT32);
    goto finish;
  }
  case SQLITE_VEC_ELEMENT_TYPE_INT8: {
    size_t outSize = dimensions * sizeof(i8);
    i8 *out = sqlite3_malloc(outSize);
    if (!out) {
      sqlite3_result_error_nomem(context);
      goto finish;
    }
    memset(out, 0, outSize);
    for (size_t i = 0; i < dimensions; i++) {
      out[i] = ((i8 *)a)[i] - ((i8 *)b)[i];
    }
    sqlite3_result_blob(context, out, outSize, sqlite3_free);
    sqlite3_result_subtype(context, SQLITE_VEC_ELEMENT_TYPE_INT8);
    goto finish;
  }
  }
finish:
  aCleanup(a);
  bCleanup(b);
  return;
}
static void vec_slice(sqlite3_context *context, int argc,
                      sqlite3_value **argv) {
  assert(argc == 3);

  void *vector;
  size_t dimensions;
  vector_cleanup cleanup;
  char *err;
  enum VectorElementType elementType;

  int rc = vector_from_value(argv[0], &vector, &dimensions, &elementType,
                             &cleanup, &err);
  if (rc != SQLITE_OK) {
    sqlite3_result_error(context, err, -1);
    sqlite3_free(err);
    return;
  }

  int start = sqlite3_value_int(argv[1]);
  int end = sqlite3_value_int(argv[2]);

  if (start < 0) {
    sqlite3_result_error(context,
                         "slice 'start' index must be a postive number.", -1);
    goto done;
  }
  if (end < 0) {
    sqlite3_result_error(context, "slice 'end' index must be a postive number.",
                         -1);
    goto done;
  }
  if (((size_t)start) > dimensions) {
    sqlite3_result_error(
        context, "slice 'start' index is greater than the number of dimensions",
        -1);
    goto done;
  }
  if (((size_t)end) > dimensions) {
    sqlite3_result_error(
        context, "slice 'end' index is greater than the number of dimensions",
        -1);
    goto done;
  }
  if (start > end) {
    sqlite3_result_error(context,
                         "slice 'start' index is greater than 'end' index", -1);
    goto done;
  }
  if (start == end) {
    sqlite3_result_error(context,
                         "slice 'start' index is equal to the 'end' index, "
                         "vectors must have non-zero length",
                         -1);
    goto done;
  }
  size_t n = end - start;

  switch (elementType) {
  case SQLITE_VEC_ELEMENT_TYPE_FLOAT32: {
    int outSize = n * sizeof(f32);
    f32 *out = sqlite3_malloc(outSize);
    if (!out) {
      sqlite3_result_error_nomem(context);
      goto done;
    }
    memset(out, 0, outSize);
    for (size_t i = 0; i < n; i++) {
      out[i] = ((f32 *)vector)[start + i];
    }
    sqlite3_result_blob(context, out, outSize, sqlite3_free);
    sqlite3_result_subtype(context, SQLITE_VEC_ELEMENT_TYPE_FLOAT32);
    goto done;
  }
  case SQLITE_VEC_ELEMENT_TYPE_INT8: {
    int outSize = n * sizeof(i8);
    i8 *out = sqlite3_malloc(outSize);
    if (!out) {
      sqlite3_result_error_nomem(context);
      goto done;
    }
    memset(out, 0, outSize);
    for (size_t i = 0; i < n; i++) {
      out[i] = ((i8 *)vector)[start + i];
    }
    sqlite3_result_blob(context, out, outSize, sqlite3_free);
    sqlite3_result_subtype(context, SQLITE_VEC_ELEMENT_TYPE_INT8);
    goto done;
  }
  case SQLITE_VEC_ELEMENT_TYPE_BIT: {
    if ((start % CHAR_BIT) != 0) {
      sqlite3_result_error(context, "start index must be divisible by 8.", -1);
      goto done;
    }
    if ((end % CHAR_BIT) != 0) {
      sqlite3_result_error(context, "end index must be divisible by 8.", -1);
      goto done;
    }
    int outSize = n / CHAR_BIT;
    u8 *out = sqlite3_malloc(outSize);
    if (!out) {
      sqlite3_result_error_nomem(context);
      goto done;
    }
    memset(out, 0, outSize);
    for (size_t i = 0; i < n / CHAR_BIT; i++) {
      out[i] = ((u8 *)vector)[(start / CHAR_BIT) + i];
    }
    sqlite3_result_blob(context, out, outSize, sqlite3_free);
    sqlite3_result_subtype(context, SQLITE_VEC_ELEMENT_TYPE_BIT);
    goto done;
  }
  }
done:
  cleanup(vector);
}

static void vec_to_json(sqlite3_context *context, int argc,
                        sqlite3_value **argv) {
  assert(argc == 1);
  void *vector;
  size_t dimensions;
  vector_cleanup cleanup;
  char *err;
  enum VectorElementType elementType;

  int rc = vector_from_value(argv[0], &vector, &dimensions, &elementType,
                             &cleanup, &err);
  if (rc != SQLITE_OK) {
    sqlite3_result_error(context, err, -1);
    sqlite3_free(err);
    return;
  }

  sqlite3_str *str = sqlite3_str_new(sqlite3_context_db_handle(context));
  sqlite3_str_appendall(str, "[");
  for (size_t i = 0; i < dimensions; i++) {
    if (i != 0) {
      sqlite3_str_appendall(str, ",");
    }
    if (elementType == SQLITE_VEC_ELEMENT_TYPE_FLOAT32) {
      sqlite3_str_appendf(str, "%f", ((f32 *)vector)[i]);
    } else if (elementType == SQLITE_VEC_ELEMENT_TYPE_INT8) {
      sqlite3_str_appendf(str, "%d", ((i8 *)vector)[i]);
    } else if (elementType == SQLITE_VEC_ELEMENT_TYPE_BIT) {
      u8 b = (((u8 *)vector)[i / 8] >> (i % CHAR_BIT)) & 1;
      sqlite3_str_appendf(str, "%d", b);
    }
  }
  sqlite3_str_appendall(str, "]");
  int len = sqlite3_str_length(str);
  char *s = sqlite3_str_finish(str);
  if (s) {
    sqlite3_result_text(context, s, len, sqlite3_free);
    sqlite3_result_subtype(context, JSON_SUBTYPE);
  } else {
    sqlite3_result_error_nomem(context);
  }
  cleanup(vector);
}

static void vec_normalize(sqlite3_context *context, int argc,
                          sqlite3_value **argv) {
  assert(argc == 1);
  void *vector;
  size_t dimensions;
  vector_cleanup cleanup;
  char *err;
  enum VectorElementType elementType;

  int rc = vector_from_value(argv[0], &vector, &dimensions, &elementType,
                             &cleanup, &err);
  if (rc != SQLITE_OK) {
    sqlite3_result_error(context, err, -1);
    sqlite3_free(err);
    return;
  }

  if (elementType != SQLITE_VEC_ELEMENT_TYPE_FLOAT32) {
    sqlite3_result_error(
        context, "only float32 vectors are supported when normalizing", -1);
    cleanup(vector);
    return;
  }

  f32 *v = (f32 *)vector;

  // Accumulate in double so that squaring small or large f32 elements does
  // not underflow or overflow, see distance_cosine_float().
  double norm = 0;
  for (size_t i = 0; i < dimensions; i++) {
    norm += (double)v[i] * (double)v[i];
  }
  norm = sqrt(norm);
  if (norm == 0) {
    // a zero vector has no direction; return NULL, not a vector of NaNs
    cleanup(vector);
    sqlite3_result_null(context);
    return;
  }

  int outSize = dimensions * sizeof(f32);
  f32 *out = sqlite3_malloc(outSize);
  if (!out) {
    cleanup(vector);
    sqlite3_result_error_code(context, SQLITE_NOMEM);
    return;
  }
  memset(out, 0, outSize);

  for (size_t i = 0; i < dimensions; i++) {
    out[i] = v[i] / norm;
  }

  sqlite3_result_blob(context, out, dimensions * sizeof(f32), sqlite3_free);
  sqlite3_result_subtype(context, SQLITE_VEC_ELEMENT_TYPE_FLOAT32);
  cleanup(vector);
}

static void _static_text_func(sqlite3_context *context, int argc,
                              sqlite3_value **argv) {
  UNUSED_PARAMETER(argc);
  UNUSED_PARAMETER(argv);
  sqlite3_result_text(context, sqlite3_user_data(context), -1, SQLITE_STATIC);
}

#pragma endregion

enum Vec0TokenType {
  TOKEN_TYPE_IDENTIFIER,
  TOKEN_TYPE_DIGIT,
  TOKEN_TYPE_LBRACKET,
  TOKEN_TYPE_RBRACKET,
  TOKEN_TYPE_PLUS,
  TOKEN_TYPE_EQ,
};
struct Vec0Token {
  enum Vec0TokenType token_type;
  char *start;
  char *end;
};

int is_alpha(char x) {
  return (x >= 'a' && x <= 'z') || (x >= 'A' && x <= 'Z');
}
int is_digit(char x) { return (x >= '0' && x <= '9'); }
int is_whitespace(char x) {
  return x == ' ' || x == '\t' || x == '\n' || x == '\r';
}

#define VEC0_TOKEN_RESULT_EOF 1
#define VEC0_TOKEN_RESULT_SOME 2
#define VEC0_TOKEN_RESULT_ERROR 3

int vec0_token_next(char *start, char *end, struct Vec0Token *out) {
  char *ptr = start;
  while (ptr < end) {
    char curr = *ptr;
    if (is_whitespace(curr)) {
      ptr++;
      continue;
    } else if (curr == '+') {
      ptr++;
      out->start = ptr;
      out->end = ptr;
      out->token_type = TOKEN_TYPE_PLUS;
      return VEC0_TOKEN_RESULT_SOME;
    } else if (curr == '[') {
      ptr++;
      out->start = ptr;
      out->end = ptr;
      out->token_type = TOKEN_TYPE_LBRACKET;
      return VEC0_TOKEN_RESULT_SOME;
    } else if (curr == ']') {
      ptr++;
      out->start = ptr;
      out->end = ptr;
      out->token_type = TOKEN_TYPE_RBRACKET;
      return VEC0_TOKEN_RESULT_SOME;
    } else if (curr == '=') {
      ptr++;
      out->start = ptr;
      out->end = ptr;
      out->token_type = TOKEN_TYPE_EQ;
      return VEC0_TOKEN_RESULT_SOME;
    } else if (is_alpha(curr)) {
      char *start = ptr;
      while (ptr < end && (is_alpha(*ptr) || is_digit(*ptr) || *ptr == '_')) {
        ptr++;
      }
      out->start = start;
      out->end = ptr;
      out->token_type = TOKEN_TYPE_IDENTIFIER;
      return VEC0_TOKEN_RESULT_SOME;
    } else if (is_digit(curr)) {
      char *start = ptr;
      while (ptr < end && (is_digit(*ptr))) {
        ptr++;
      }
      out->start = start;
      out->end = ptr;
      out->token_type = TOKEN_TYPE_DIGIT;
      return VEC0_TOKEN_RESULT_SOME;
    } else {
      return VEC0_TOKEN_RESULT_ERROR;
    }
  }
  return VEC0_TOKEN_RESULT_EOF;
}

struct Vec0Scanner {
  char *start;
  char *end;
  char *ptr;
};

void vec0_scanner_init(struct Vec0Scanner *scanner, const char *source,
                       int source_length) {
  scanner->start = (char *)source;
  scanner->end = (char *)source + source_length;
  scanner->ptr = (char *)source;
}
int vec0_scanner_next(struct Vec0Scanner *scanner, struct Vec0Token *out) {
  int rc = vec0_token_next(scanner->start, scanner->end, out);
  if (rc == VEC0_TOKEN_RESULT_SOME) {
    scanner->start = out->end;
  }
  return rc;
}

/**
 * @brief Whether an identifier token is the given keyword, compared ASCII
 * case-insensitively.
 *
 * The partition key, primary key, auxiliary, and metadata column parsers are
 * strict only when creating a table: CREATE requires whole keywords and nothing
 * after the definition. CREATE used to accept any prefix of a keyword, such as
 * `te` for `text`, and ignore tokens after the definition, such as `collate
 * nocase`. vec0 re-parses the stored declaration on every connect, so connect
 * still accepts both, and tables declared that way still open.
 *
 * @param isCreate: true to require the whole keyword, false to accept any
 * prefix of it.
 */
static int vec0_token_is_keyword(const struct Vec0Token *token,
                                 const char *keyword, bool isCreate) {
  int n = token->end - token->start;
  if (isCreate && n != (int)strlen(keyword)) {
    return 0;
  }
  return sqlite3_strnicmp(token->start, keyword, n) == 0;
}

int vec0_parse_table_option(const char *source, int source_length,
                            char **out_key, int *out_key_length,
                            char **out_value, int *out_value_length) {
  int rc;
  struct Vec0Scanner scanner;
  struct Vec0Token token;
  char *key;
  char *value;
  int keyLength, valueLength;

  vec0_scanner_init(&scanner, source, source_length);

  rc = vec0_scanner_next(&scanner, &token);
  if (rc != VEC0_TOKEN_RESULT_SOME ||
      token.token_type != TOKEN_TYPE_IDENTIFIER) {
    return SQLITE_EMPTY;
  }
  key = token.start;
  keyLength = token.end - token.start;

  rc = vec0_scanner_next(&scanner, &token);
  if (rc != VEC0_TOKEN_RESULT_SOME || token.token_type != TOKEN_TYPE_EQ) {
    return SQLITE_EMPTY;
  }

  rc = vec0_scanner_next(&scanner, &token);
  if (rc != VEC0_TOKEN_RESULT_SOME ||
      !((token.token_type == TOKEN_TYPE_IDENTIFIER) ||
        (token.token_type == TOKEN_TYPE_DIGIT))) {
    return SQLITE_ERROR;
  }
  value = token.start;
  valueLength = token.end - token.start;

  rc = vec0_scanner_next(&scanner, &token);
  if (rc == VEC0_TOKEN_RESULT_EOF) {
    *out_key = key;
    *out_key_length = keyLength;
    *out_value = value;
    *out_value_length = valueLength;
    return SQLITE_OK;
  }
  return SQLITE_ERROR;
}
/**
 * @brief Parse an argv[i] entry of a vec0 virtual table definition, and see if
 * it's a PARTITION KEY definition.
 *
 * @param source: argv[i] source string
 * @param source_length: length of the source string
 * @param out_column_name: If it is a partition key, the output column name.
 * Same lifetime as source, points to specific char *
 * @param out_column_name_length: Length of out_column_name in bytes
 * @param out_column_type: SQLITE_TEXT or SQLITE_INTEGER.
 * @param isCreate: true when creating the table, which requires whole keywords
 * and nothing after the definition, see vec0_token_is_keyword().
 * @return int: SQLITE_EMPTY if not a PK, SQLITE_OK if it is.
 */
int vec0_parse_partition_key_definition(const char *source, int source_length,
                                        char **out_column_name,
                                        int *out_column_name_length,
                                        int *out_column_type, bool isCreate) {
  struct Vec0Scanner scanner;
  struct Vec0Token token;
  char *column_name;
  int column_name_length;
  int column_type;
  vec0_scanner_init(&scanner, source, source_length);

  // Check first token is identifier, will be the column name
  int rc = vec0_scanner_next(&scanner, &token);
  if (rc != VEC0_TOKEN_RESULT_SOME ||
      token.token_type != TOKEN_TYPE_IDENTIFIER) {
    return SQLITE_EMPTY;
  }

  column_name = token.start;
  column_name_length = token.end - token.start;

  // Check the next token matches "text" or "integer", as column type
  rc = vec0_scanner_next(&scanner, &token);
  if (rc != VEC0_TOKEN_RESULT_SOME ||
      token.token_type != TOKEN_TYPE_IDENTIFIER) {
    return SQLITE_EMPTY;
  }
  if (vec0_token_is_keyword(&token, "text", isCreate)) {
    column_type = SQLITE_TEXT;
  } else if (vec0_token_is_keyword(&token, "int", isCreate) ||
             vec0_token_is_keyword(&token, "integer", isCreate)) {
    column_type = SQLITE_INTEGER;
  } else {
    return SQLITE_EMPTY;
  }

  // Check the next token is identifier and matches "partition"
  rc = vec0_scanner_next(&scanner, &token);
  if (rc != VEC0_TOKEN_RESULT_SOME ||
      token.token_type != TOKEN_TYPE_IDENTIFIER) {
    return SQLITE_EMPTY;
  }
  if (!vec0_token_is_keyword(&token, "partition", isCreate)) {
    return SQLITE_EMPTY;
  }

  // Check the next token is identifier and matches "key"
  rc = vec0_scanner_next(&scanner, &token);
  if (rc != VEC0_TOKEN_RESULT_SOME ||
      token.token_type != TOKEN_TYPE_IDENTIFIER) {
    return SQLITE_EMPTY;
  }
  if (!vec0_token_is_keyword(&token, "key", isCreate)) {
    return SQLITE_EMPTY;
  }

  if (isCreate &&
      vec0_scanner_next(&scanner, &token) != VEC0_TOKEN_RESULT_EOF) {
    return SQLITE_EMPTY;
  }

  *out_column_name = column_name;
  *out_column_name_length = column_name_length;
  *out_column_type = column_type;

  return SQLITE_OK;
}

/**
 * @brief Parse an argv[i] entry of a vec0 virtual table definition, and see if
 * it's an auxiliar column definition, ie `+[name] [type]` like `+contents text`
 *
 * @param source: argv[i] source string
 * @param source_length: length of the source string
 * @param out_column_name: If it is a partition key, the output column name.
 * Same lifetime as source, points to specific char *
 * @param out_column_name_length: Length of out_column_name in bytes
 * @param out_column_type: SQLITE_TEXT, SQLITE_INTEGER, SQLITE_FLOAT, or
 * SQLITE_BLOB.
 * @param isCreate: true when creating the table, which requires whole keywords
 * and nothing after the definition, see vec0_token_is_keyword().
 * @return int: SQLITE_EMPTY if not an aux column, SQLITE_OK if it is.
 */
int vec0_parse_auxiliary_column_definition(
    const char *source, int source_length, char **out_column_name,
    int *out_column_name_length, int *out_column_type, bool isCreate) {
  struct Vec0Scanner scanner;
  struct Vec0Token token;
  char *column_name;
  int column_name_length;
  int column_type;
  vec0_scanner_init(&scanner, source, source_length);

  // Check first token is '+', which denotes aux columns
  int rc = vec0_scanner_next(&scanner, &token);
  if (rc != VEC0_TOKEN_RESULT_SOME || token.token_type != TOKEN_TYPE_PLUS) {
    return SQLITE_EMPTY;
  }

  rc = vec0_scanner_next(&scanner, &token);
  if (rc != VEC0_TOKEN_RESULT_SOME ||
      token.token_type != TOKEN_TYPE_IDENTIFIER) {
    return SQLITE_EMPTY;
  }

  column_name = token.start;
  column_name_length = token.end - token.start;

  // Check the next token matches "text" or "integer", as column type
  rc = vec0_scanner_next(&scanner, &token);
  if (rc != VEC0_TOKEN_RESULT_SOME ||
      token.token_type != TOKEN_TYPE_IDENTIFIER) {
    return SQLITE_EMPTY;
  }
  if (vec0_token_is_keyword(&token, "text", isCreate)) {
    column_type = SQLITE_TEXT;
  } else if (vec0_token_is_keyword(&token, "int", isCreate) ||
             vec0_token_is_keyword(&token, "integer", isCreate)) {
    column_type = SQLITE_INTEGER;
  } else if (vec0_token_is_keyword(&token, "float", isCreate) ||
             vec0_token_is_keyword(&token, "double", isCreate)) {
    column_type = SQLITE_FLOAT;
  } else if (vec0_token_is_keyword(&token, "blob", isCreate)) {
    column_type = SQLITE_BLOB;
  } else {
    return SQLITE_EMPTY;
  }

  if (isCreate &&
      vec0_scanner_next(&scanner, &token) != VEC0_TOKEN_RESULT_EOF) {
    return SQLITE_EMPTY;
  }

  *out_column_name = column_name;
  *out_column_name_length = column_name_length;
  *out_column_type = column_type;

  return SQLITE_OK;
}

typedef enum {
  VEC0_METADATA_COLUMN_KIND_BOOLEAN,
  VEC0_METADATA_COLUMN_KIND_INTEGER,
  VEC0_METADATA_COLUMN_KIND_FLOAT,
  VEC0_METADATA_COLUMN_KIND_TEXT,
  // future: blob, date, datetime
} vec0_metadata_column_kind;

/**
 * @brief Parse an argv[i] entry of a vec0 virtual table definition, and see if
 * it's an metadata column definition, ie `[name] [type]` like `is_released
 * boolean`
 *
 * @param source: argv[i] source string
 * @param source_length: length of the source string
 * @param out_column_name: If it is a metadata column, the output column name.
 * Same lifetime as source, points to specific char *
 * @param out_column_name_length: Length of out_column_name in bytes
 * @param out_column_type: one of vec0_metadata_column_kind
 * @param isCreate: true when creating the table, which requires whole keywords
 * and nothing after the definition, see vec0_token_is_keyword().
 * @return int: SQLITE_EMPTY if not an metadata column, SQLITE_OK if it is.
 */
int vec0_parse_metadata_column_definition(
    const char *source, int source_length, char **out_column_name,
    int *out_column_name_length, vec0_metadata_column_kind *out_column_type,
    bool isCreate) {
  struct Vec0Scanner scanner;
  struct Vec0Token token;
  char *column_name;
  int column_name_length;
  vec0_metadata_column_kind column_type;
  int rc;
  vec0_scanner_init(&scanner, source, source_length);

  rc = vec0_scanner_next(&scanner, &token);
  if (rc != VEC0_TOKEN_RESULT_SOME ||
      token.token_type != TOKEN_TYPE_IDENTIFIER) {
    return SQLITE_EMPTY;
  }

  column_name = token.start;
  column_name_length = token.end - token.start;

  // Check the next token matches a valid metadata type
  rc = vec0_scanner_next(&scanner, &token);
  if (rc != VEC0_TOKEN_RESULT_SOME ||
      token.token_type != TOKEN_TYPE_IDENTIFIER) {
    return SQLITE_EMPTY;
  }
  if (vec0_token_is_keyword(&token, "boolean", isCreate) ||
      vec0_token_is_keyword(&token, "bool", isCreate)) {
    column_type = VEC0_METADATA_COLUMN_KIND_BOOLEAN;
  } else if (vec0_token_is_keyword(&token, "int64", isCreate) ||
             vec0_token_is_keyword(&token, "integer64", isCreate) ||
             vec0_token_is_keyword(&token, "integer", isCreate) ||
             vec0_token_is_keyword(&token, "int", isCreate)) {
    column_type = VEC0_METADATA_COLUMN_KIND_INTEGER;
  } else if (vec0_token_is_keyword(&token, "float", isCreate) ||
             vec0_token_is_keyword(&token, "double", isCreate) ||
             vec0_token_is_keyword(&token, "float64", isCreate) ||
             vec0_token_is_keyword(&token, "f64", isCreate)) {
    column_type = VEC0_METADATA_COLUMN_KIND_FLOAT;
  } else if (vec0_token_is_keyword(&token, "text", isCreate)) {
    column_type = VEC0_METADATA_COLUMN_KIND_TEXT;
  } else {
    return SQLITE_EMPTY;
  }

  if (isCreate &&
      vec0_scanner_next(&scanner, &token) != VEC0_TOKEN_RESULT_EOF) {
    return SQLITE_EMPTY;
  }

  *out_column_name = column_name;
  *out_column_name_length = column_name_length;
  *out_column_type = column_type;

  return SQLITE_OK;
}

/**
 * @brief Parse an argv[i] entry of a vec0 virtual table definition, and see if
 * it's a PRIMARY KEY definition.
 *
 * @param source: argv[i] source string
 * @param source_length: length of the source string
 * @param out_column_name: If it is a PK, the output column name. Same lifetime
 * as source, points to specific char *
 * @param out_column_name_length: Length of out_column_name in bytes
 * @param out_column_type: SQLITE_TEXT or SQLITE_INTEGER.
 * @param isCreate: true when creating the table, which requires whole keywords
 * and nothing after the definition, see vec0_token_is_keyword().
 * @return int: SQLITE_EMPTY if not a PK, SQLITE_OK if it is.
 */
int vec0_parse_primary_key_definition(const char *source, int source_length,
                                      char **out_column_name,
                                      int *out_column_name_length,
                                      int *out_column_type, bool isCreate) {
  struct Vec0Scanner scanner;
  struct Vec0Token token;
  char *column_name;
  int column_name_length;
  int column_type;
  vec0_scanner_init(&scanner, source, source_length);

  // Check first token is identifier, will be the column name
  int rc = vec0_scanner_next(&scanner, &token);
  if (rc != VEC0_TOKEN_RESULT_SOME ||
      token.token_type != TOKEN_TYPE_IDENTIFIER) {
    return SQLITE_EMPTY;
  }

  column_name = token.start;
  column_name_length = token.end - token.start;

  // Check the next token matches "text" or "integer", as column type
  rc = vec0_scanner_next(&scanner, &token);
  if (rc != VEC0_TOKEN_RESULT_SOME ||
      token.token_type != TOKEN_TYPE_IDENTIFIER) {
    return SQLITE_EMPTY;
  }
  if (vec0_token_is_keyword(&token, "text", isCreate)) {
    column_type = SQLITE_TEXT;
  } else if (vec0_token_is_keyword(&token, "int", isCreate) ||
             vec0_token_is_keyword(&token, "integer", isCreate)) {
    column_type = SQLITE_INTEGER;
  } else {
    return SQLITE_EMPTY;
  }

  // Check the next token is identifier and matches "primary"
  rc = vec0_scanner_next(&scanner, &token);
  if (rc != VEC0_TOKEN_RESULT_SOME ||
      token.token_type != TOKEN_TYPE_IDENTIFIER) {
    return SQLITE_EMPTY;
  }
  if (!vec0_token_is_keyword(&token, "primary", isCreate)) {
    return SQLITE_EMPTY;
  }

  // Check the next token is identifier and matches "key"
  rc = vec0_scanner_next(&scanner, &token);
  if (rc != VEC0_TOKEN_RESULT_SOME ||
      token.token_type != TOKEN_TYPE_IDENTIFIER) {
    return SQLITE_EMPTY;
  }
  if (!vec0_token_is_keyword(&token, "key", isCreate)) {
    return SQLITE_EMPTY;
  }

  if (isCreate &&
      vec0_scanner_next(&scanner, &token) != VEC0_TOKEN_RESULT_EOF) {
    return SQLITE_EMPTY;
  }

  *out_column_name = column_name;
  *out_column_name_length = column_name_length;
  *out_column_type = column_type;

  return SQLITE_OK;
}

enum Vec0DistanceMetrics {
  VEC0_DISTANCE_METRIC_L2 = 1,
  VEC0_DISTANCE_METRIC_COSINE = 2,
  VEC0_DISTANCE_METRIC_L1 = 3,
};

struct VectorColumnDefinition {
  char *name;
  int name_length;
  size_t dimensions;
  enum VectorElementType element_type;
  enum Vec0DistanceMetrics distance_metric;
};

struct Vec0PartitionColumnDefinition {
  int type;
  char *name;
  int name_length;
};

struct Vec0AuxiliaryColumnDefinition {
  int type;
  char *name;
  int name_length;
};
struct Vec0MetadataColumnDefinition {
  vec0_metadata_column_kind kind;
  char *name;
  int name_length;
};

size_t vector_byte_size(enum VectorElementType element_type,
                        size_t dimensions) {
  switch (element_type) {
  case SQLITE_VEC_ELEMENT_TYPE_FLOAT32:
    return dimensions * sizeof(f32);
  case SQLITE_VEC_ELEMENT_TYPE_INT8:
    return dimensions * sizeof(i8);
  case SQLITE_VEC_ELEMENT_TYPE_BIT:
    return dimensions / CHAR_BIT;
  }
  return 0;
}

size_t vector_column_byte_size(struct VectorColumnDefinition column) {
  return vector_byte_size(column.element_type, column.dimensions);
}

/**
 * @brief Parse an vec0 vtab argv[i] column definition and see if
 * it's a vector column defintion, ex `contents_embedding float[768]`.
 *
 * @param source vec0 argv[i] item
 * @param source_length length of source in bytes
 * @param outColumn Output the parse vector column to this struct, if success
 * @param strict true to require an identifier for the name, '[' and ']' around
 * the dimensions, and identifiers for option keys and values; false to accept
 * any token there, as vec0 2.0.2 and earlier did when they created tables such
 * as `5 float[4]` and `a float[4] +=cosine`
 * @return int SQLITE_OK on success, SQLITE_EMPTY is it's not a vector column
 * definition, SQLITE_ERROR on error.
 */
int vec0_parse_vector_column(const char *source, int source_length,
                             struct VectorColumnDefinition *outColumn,
                             bool strict) {
  // parses a vector column definition like so:
  // "abc float[123]", "abc_123 bit[1234]", eetc.
  // https://github.com/asg017/sqlite-vec/issues/46
  int rc;
  struct Vec0Scanner scanner;
  struct Vec0Token token;

  char *name;
  int nameLength;
  enum VectorElementType elementType;
  enum Vec0DistanceMetrics distanceMetric = VEC0_DISTANCE_METRIC_L2;
  int dimensions;

  vec0_scanner_init(&scanner, source, source_length);

  // starts with an identifier
  rc = vec0_scanner_next(&scanner, &token);

  if (rc != VEC0_TOKEN_RESULT_SOME ||
      (strict && token.token_type != TOKEN_TYPE_IDENTIFIER)) {
    return SQLITE_EMPTY;
  }

  name = token.start;
  nameLength = token.end - token.start;

  // vector column type comes next: float, int, or bit
  rc = vec0_scanner_next(&scanner, &token);

  if (rc != VEC0_TOKEN_RESULT_SOME ||
      token.token_type != TOKEN_TYPE_IDENTIFIER) {
    return SQLITE_EMPTY;
  }
  if (sqlite3_strnicmp(token.start, "float", 5) == 0 ||
      sqlite3_strnicmp(token.start, "f32", 3) == 0) {
    elementType = SQLITE_VEC_ELEMENT_TYPE_FLOAT32;
  } else if (sqlite3_strnicmp(token.start, "int8", 4) == 0 ||
             sqlite3_strnicmp(token.start, "i8", 2) == 0) {
    elementType = SQLITE_VEC_ELEMENT_TYPE_INT8;
  } else if (sqlite3_strnicmp(token.start, "bit", 3) == 0) {
    elementType = SQLITE_VEC_ELEMENT_TYPE_BIT;
  } else {
    return SQLITE_EMPTY;
  }

  // left '[' bracket
  rc = vec0_scanner_next(&scanner, &token);
  if (rc != VEC0_TOKEN_RESULT_SOME ||
      (strict && token.token_type != TOKEN_TYPE_LBRACKET)) {
    return SQLITE_EMPTY;
  }

  // digit, for vector dimension length
  rc = vec0_scanner_next(&scanner, &token);
  if (rc != VEC0_TOKEN_RESULT_SOME || token.token_type != TOKEN_TYPE_DIGIT) {
    return SQLITE_ERROR;
  }
  errno = 0;
  char *endptr;
  long parsed_dimensions = strtol(token.start, &endptr, 10);
  if (errno == ERANGE || endptr != token.end || parsed_dimensions <= 0 ||
      parsed_dimensions > INT_MAX) {
    return SQLITE_ERROR;
  }
  dimensions = (int)parsed_dimensions;

  // // right ']' bracket
  rc = vec0_scanner_next(&scanner, &token);
  if (rc != VEC0_TOKEN_RESULT_SOME ||
      (strict && token.token_type != TOKEN_TYPE_RBRACKET)) {
    return SQLITE_ERROR;
  }

  // any other tokens left should be column-level options , ex `key=value`
  // ex `distance_metric=L2 distance_metric=cosine` should error
  while (1) {
    // should be EOF or identifier (option key)
    rc = vec0_scanner_next(&scanner, &token);
    if (rc == VEC0_TOKEN_RESULT_EOF) {
      break;
    }

    if (rc != VEC0_TOKEN_RESULT_SOME ||
        (strict && token.token_type != TOKEN_TYPE_IDENTIFIER)) {
      return SQLITE_ERROR;
    }

    char *key = token.start;
    int keyLength = token.end - token.start;

    if (sqlite3_strnicmp(key, "distance_metric", keyLength) == 0) {

      if (elementType == SQLITE_VEC_ELEMENT_TYPE_BIT) {
        return SQLITE_ERROR;
      }
      // ensure equal sign after distance_metric
      rc = vec0_scanner_next(&scanner, &token);
      if (rc != VEC0_TOKEN_RESULT_SOME || token.token_type != TOKEN_TYPE_EQ) {
        return SQLITE_ERROR;
      }

      // distance_metric value, an identifier (L2, cosine, etc)
      rc = vec0_scanner_next(&scanner, &token);
      if (rc != VEC0_TOKEN_RESULT_SOME ||
          (strict && token.token_type != TOKEN_TYPE_IDENTIFIER)) {
        return SQLITE_ERROR;
      }

      char *value = token.start;
      int valueLength = token.end - token.start;
      if (sqlite3_strnicmp(value, "l2", valueLength) == 0) {
        distanceMetric = VEC0_DISTANCE_METRIC_L2;
      } else if (sqlite3_strnicmp(value, "l1", valueLength) == 0) {
        distanceMetric = VEC0_DISTANCE_METRIC_L1;
      } else if (sqlite3_strnicmp(value, "cosine", valueLength) == 0) {
        distanceMetric = VEC0_DISTANCE_METRIC_COSINE;
      } else {
        return SQLITE_ERROR;
      }
    }
    // unknown key
    else {
      return SQLITE_ERROR;
    }
  }

  outColumn->name = sqlite3_mprintf("%.*s", nameLength, name);
  if (!outColumn->name) {
    return SQLITE_ERROR;
  }
  outColumn->name_length = nameLength;
  outColumn->distance_metric = distanceMetric;
  outColumn->element_type = elementType;
  outColumn->dimensions = dimensions;
  return SQLITE_OK;
}

#pragma region vec_each table function

typedef struct vec_each_vtab vec_each_vtab;
struct vec_each_vtab {
  sqlite3_vtab base;
};

typedef struct vec_each_cursor vec_each_cursor;
struct vec_each_cursor {
  sqlite3_vtab_cursor base;
  i64 iRowid;
  enum VectorElementType vector_type;
  void *vector;
  size_t dimensions;
  vector_cleanup cleanup;
};

static int vec_eachConnect(sqlite3 *db, void *pAux, int argc,
                           const char *const *argv, sqlite3_vtab **ppVtab,
                           char **pzErr) {
  UNUSED_PARAMETER(pAux);
  UNUSED_PARAMETER(argc);
  UNUSED_PARAMETER(argv);
  UNUSED_PARAMETER(pzErr);
  vec_each_vtab *pNew;
  int rc;

  rc = sqlite3_declare_vtab(db, "CREATE TABLE x(value, vector hidden)");
#define VEC_EACH_COLUMN_VALUE 0
#define VEC_EACH_COLUMN_VECTOR 1
  if (rc == SQLITE_OK) {
    pNew = sqlite3_malloc(sizeof(*pNew));
    *ppVtab = (sqlite3_vtab *)pNew;
    if (pNew == 0)
      return SQLITE_NOMEM;
    memset(pNew, 0, sizeof(*pNew));
  }
  return rc;
}

static int vec_eachDisconnect(sqlite3_vtab *pVtab) {
  vec_each_vtab *p = (vec_each_vtab *)pVtab;
  sqlite3_free(p);
  return SQLITE_OK;
}

static int vec_eachOpen(sqlite3_vtab *p, sqlite3_vtab_cursor **ppCursor) {
  UNUSED_PARAMETER(p);
  vec_each_cursor *pCur;
  pCur = sqlite3_malloc(sizeof(*pCur));
  if (pCur == 0)
    return SQLITE_NOMEM;
  memset(pCur, 0, sizeof(*pCur));
  *ppCursor = &pCur->base;
  return SQLITE_OK;
}

static int vec_eachClose(sqlite3_vtab_cursor *cur) {
  vec_each_cursor *pCur = (vec_each_cursor *)cur;
  if (pCur->vector) {
    pCur->cleanup(pCur->vector);
  }
  sqlite3_free(pCur);
  return SQLITE_OK;
}

static int vec_eachBestIndex(sqlite3_vtab *pVTab,
                             sqlite3_index_info *pIdxInfo) {
  UNUSED_PARAMETER(pVTab);
  int hasVector = 0;
  for (int i = 0; i < pIdxInfo->nConstraint; i++) {
    const struct sqlite3_index_constraint *pCons = &pIdxInfo->aConstraint[i];
    // printf("i=%d iColumn=%d, op=%d, usable=%d\n", i, pCons->iColumn,
    // pCons->op, pCons->usable);
    switch (pCons->iColumn) {
    case VEC_EACH_COLUMN_VECTOR: {
      if (pCons->op == SQLITE_INDEX_CONSTRAINT_EQ && pCons->usable) {
        hasVector = 1;
        pIdxInfo->aConstraintUsage[i].argvIndex = 1;
        pIdxInfo->aConstraintUsage[i].omit = 1;
      }
      break;
    }
    }
  }
  if (!hasVector) {
    return SQLITE_CONSTRAINT;
  }

  pIdxInfo->estimatedCost = (double)100000;
  pIdxInfo->estimatedRows = 100000;

  return SQLITE_OK;
}

static int vec_eachFilter(sqlite3_vtab_cursor *pVtabCursor, int idxNum,
                          const char *idxStr, int argc, sqlite3_value **argv) {
  UNUSED_PARAMETER(idxNum);
  UNUSED_PARAMETER(idxStr);
  assert(argc == 1);
  vec_each_cursor *pCur = (vec_each_cursor *)pVtabCursor;

  if (pCur->vector) {
    pCur->cleanup(pCur->vector);
    pCur->vector = NULL;
  }

  char *pzErrMsg;
  int rc = vector_from_value(argv[0], &pCur->vector, &pCur->dimensions,
                             &pCur->vector_type, &pCur->cleanup, &pzErrMsg);
  if (rc != SQLITE_OK) {
    sqlite3_free(pzErrMsg);
    return SQLITE_ERROR;
  }
  pCur->iRowid = 0;
  return SQLITE_OK;
}

static int vec_eachRowid(sqlite3_vtab_cursor *cur, sqlite_int64 *pRowid) {
  vec_each_cursor *pCur = (vec_each_cursor *)cur;
  *pRowid = pCur->iRowid;
  return SQLITE_OK;
}

static int vec_eachEof(sqlite3_vtab_cursor *cur) {
  vec_each_cursor *pCur = (vec_each_cursor *)cur;
  return pCur->iRowid >= (i64)pCur->dimensions;
}

static int vec_eachNext(sqlite3_vtab_cursor *cur) {
  vec_each_cursor *pCur = (vec_each_cursor *)cur;
  pCur->iRowid++;
  return SQLITE_OK;
}

static int vec_eachColumn(sqlite3_vtab_cursor *cur, sqlite3_context *context,
                          int i) {
  vec_each_cursor *pCur = (vec_each_cursor *)cur;
  switch (i) {
  case VEC_EACH_COLUMN_VALUE:
    switch (pCur->vector_type) {
    case SQLITE_VEC_ELEMENT_TYPE_FLOAT32: {
      sqlite3_result_double(context, ((f32 *)pCur->vector)[pCur->iRowid]);
      break;
    }
    case SQLITE_VEC_ELEMENT_TYPE_BIT: {
      u8 x = ((u8 *)pCur->vector)[pCur->iRowid / CHAR_BIT];
      sqlite3_result_int(context,
                         (x & (0b10000000 >> ((pCur->iRowid % CHAR_BIT)))) > 0);
      break;
    }
    case SQLITE_VEC_ELEMENT_TYPE_INT8: {
      sqlite3_result_int(context, ((i8 *)pCur->vector)[pCur->iRowid]);
      break;
    }
    }

    break;
  }
  return SQLITE_OK;
}

static sqlite3_module vec_eachModule = {
    /* iVersion    */ 0,
    /* xCreate     */ 0,
    /* xConnect    */ vec_eachConnect,
    /* xBestIndex  */ vec_eachBestIndex,
    /* xDisconnect */ vec_eachDisconnect,
    /* xDestroy    */ 0,
    /* xOpen       */ vec_eachOpen,
    /* xClose      */ vec_eachClose,
    /* xFilter     */ vec_eachFilter,
    /* xNext       */ vec_eachNext,
    /* xEof        */ vec_eachEof,
    /* xColumn     */ vec_eachColumn,
    /* xRowid      */ vec_eachRowid,
    /* xUpdate     */ 0,
    /* xBegin      */ 0,
    /* xSync       */ 0,
    /* xCommit     */ 0,
    /* xRollback   */ 0,
    /* xFindMethod */ 0,
    /* xRename     */ 0,
    /* xSavepoint  */ 0,
    /* xRelease    */ 0,
    /* xRollbackTo */ 0,
    /* xShadowName */ 0,
#if SQLITE_VERSION_NUMBER >= 3044000
    /* xIntegrity  */ 0
#endif
};

#pragma endregion

#pragma region vec_npy_each table function

enum NpyTokenType {
  NPY_TOKEN_TYPE_IDENTIFIER,
  NPY_TOKEN_TYPE_NUMBER,
  NPY_TOKEN_TYPE_LPAREN,
  NPY_TOKEN_TYPE_RPAREN,
  NPY_TOKEN_TYPE_LBRACE,
  NPY_TOKEN_TYPE_RBRACE,
  NPY_TOKEN_TYPE_COLON,
  NPY_TOKEN_TYPE_COMMA,
  NPY_TOKEN_TYPE_STRING,
  NPY_TOKEN_TYPE_FALSE,
};

struct NpyToken {
  enum NpyTokenType token_type;
  unsigned char *start;
  unsigned char *end;
};

int npy_token_next(unsigned char *start, unsigned char *end,
                   struct NpyToken *out) {
  unsigned char *ptr = start;
  while (ptr < end) {
    unsigned char curr = *ptr;
    if (is_whitespace(curr)) {
      ptr++;
      continue;
    } else if (curr == '(') {
      out->start = ptr++;
      out->end = ptr;
      out->token_type = NPY_TOKEN_TYPE_LPAREN;
      return VEC0_TOKEN_RESULT_SOME;
    } else if (curr == ')') {
      out->start = ptr++;
      out->end = ptr;
      out->token_type = NPY_TOKEN_TYPE_RPAREN;
      return VEC0_TOKEN_RESULT_SOME;
    } else if (curr == '{') {
      out->start = ptr++;
      out->end = ptr;
      out->token_type = NPY_TOKEN_TYPE_LBRACE;
      return VEC0_TOKEN_RESULT_SOME;
    } else if (curr == '}') {
      out->start = ptr++;
      out->end = ptr;
      out->token_type = NPY_TOKEN_TYPE_RBRACE;
      return VEC0_TOKEN_RESULT_SOME;
    } else if (curr == ':') {
      out->start = ptr++;
      out->end = ptr;
      out->token_type = NPY_TOKEN_TYPE_COLON;
      return VEC0_TOKEN_RESULT_SOME;
    } else if (curr == ',') {
      out->start = ptr++;
      out->end = ptr;
      out->token_type = NPY_TOKEN_TYPE_COMMA;
      return VEC0_TOKEN_RESULT_SOME;
    } else if (curr == '\'') {
      unsigned char *start = ptr;
      ptr++;
      while (ptr < end) {
        if ((*ptr) == '\'') {
          break;
        }
        ptr++;
      }
      if (ptr >= end || (*ptr) != '\'') {
        return VEC0_TOKEN_RESULT_ERROR;
      }
      out->start = start;
      out->end = ++ptr;
      out->token_type = NPY_TOKEN_TYPE_STRING;
      return VEC0_TOKEN_RESULT_SOME;
    } else if (curr == 'F' && (size_t)(end - ptr) >= strlen("False") &&
               strncmp((char *)ptr, "False", strlen("False")) == 0) {
      out->start = ptr;
      out->end = (ptr + (int)strlen("False"));
      ptr = out->end;
      out->token_type = NPY_TOKEN_TYPE_FALSE;
      return VEC0_TOKEN_RESULT_SOME;
    } else if (is_digit(curr)) {
      unsigned char *start = ptr;
      while (ptr < end && (is_digit(*ptr))) {
        ptr++;
      }
      out->start = start;
      out->end = ptr;
      out->token_type = NPY_TOKEN_TYPE_NUMBER;
      return VEC0_TOKEN_RESULT_SOME;
    } else {
      return VEC0_TOKEN_RESULT_ERROR;
    }
  }
  return VEC0_TOKEN_RESULT_ERROR;
}

struct NpyScanner {
  unsigned char *start;
  unsigned char *end;
  unsigned char *ptr;
};

void npy_scanner_init(struct NpyScanner *scanner, const unsigned char *source,
                      int source_length) {
  scanner->start = (unsigned char *)source;
  scanner->end = (unsigned char *)source + source_length;
  scanner->ptr = (unsigned char *)source;
}

int npy_scanner_next(struct NpyScanner *scanner, struct NpyToken *out) {
  int rc = npy_token_next(scanner->start, scanner->end, out);
  if (rc == VEC0_TOKEN_RESULT_SOME) {
    scanner->start = out->end;
  }
  return rc;
}

// Converts a shape number token to a size_t. The header is not NUL-terminated,
// so strtol() could read past a number that ends at the end of the header.
// Saturates at SIZE_MAX instead of wrapping.
static size_t npy_token_to_size(const struct NpyToken *token) {
  size_t value = 0;
  for (const unsigned char *p = token->start; p < token->end; p++) {
    size_t digit = (size_t)(*p - '0');
    if (value > (SIZE_MAX - digit) / 10) {
      return SIZE_MAX;
    }
    value = value * 10 + digit;
  }
  return value;
}

#define NPY_PARSE_ERROR "Error parsing numpy array: "
int parse_npy_header(sqlite3_vtab *pVTab, const unsigned char *header,
                     size_t headerLength,
                     enum VectorElementType *out_element_type,
                     int *fortran_order, size_t *numElements,
                     size_t *numDimensions) {

  struct NpyScanner scanner;
  struct NpyToken token;
  int rc;
  int sawDescr = 0;
  int sawFortranOrder = 0;
  int sawShape = 0;
  npy_scanner_init(&scanner, header, headerLength);

  if (npy_scanner_next(&scanner, &token) != VEC0_TOKEN_RESULT_SOME ||
      token.token_type != NPY_TOKEN_TYPE_LBRACE) {
    vtab_set_error(pVTab,
                   NPY_PARSE_ERROR "numpy header did not start with '{'");
    return SQLITE_ERROR;
  }
  while (1) {
    rc = npy_scanner_next(&scanner, &token);
    if (rc != VEC0_TOKEN_RESULT_SOME) {
      vtab_set_error(pVTab, NPY_PARSE_ERROR "expected key in numpy header");
      return SQLITE_ERROR;
    }

    if (token.token_type == NPY_TOKEN_TYPE_RBRACE) {
      break;
    }
    if (token.token_type != NPY_TOKEN_TYPE_STRING) {
      vtab_set_error(pVTab, NPY_PARSE_ERROR
                     "expected a string as key in numpy header");
      return SQLITE_ERROR;
    }
    unsigned char *key = token.start;

    rc = npy_scanner_next(&scanner, &token);
    if ((rc != VEC0_TOKEN_RESULT_SOME) ||
        (token.token_type != NPY_TOKEN_TYPE_COLON)) {
      vtab_set_error(pVTab, NPY_PARSE_ERROR
                     "expected a ':' after key in numpy header");
      return SQLITE_ERROR;
    }

    if (strncmp((char *)key, "'descr'", strlen("'descr'")) == 0) {
      rc = npy_scanner_next(&scanner, &token);
      if ((rc != VEC0_TOKEN_RESULT_SOME) ||
          (token.token_type != NPY_TOKEN_TYPE_STRING)) {
        vtab_set_error(pVTab, NPY_PARSE_ERROR
                       "expected a string value after 'descr' key");
        return SQLITE_ERROR;
      }
      if (strncmp((char *)token.start, "'<f4'", strlen("'<f4'")) != 0) {
        vtab_set_error(
            pVTab, NPY_PARSE_ERROR
            "Only '<f4' values are supported in sqlite-vec numpy functions");
        return SQLITE_ERROR;
      }
      *out_element_type = SQLITE_VEC_ELEMENT_TYPE_FLOAT32;
      sawDescr = 1;
    } else if (strncmp((char *)key, "'fortran_order'",
                       strlen("'fortran_order'")) == 0) {
      rc = npy_scanner_next(&scanner, &token);
      if (rc != VEC0_TOKEN_RESULT_SOME ||
          token.token_type != NPY_TOKEN_TYPE_FALSE) {
        vtab_set_error(pVTab, NPY_PARSE_ERROR
                       "Only fortran_order = False is supported in sqlite-vec "
                       "numpy functions");
        return SQLITE_ERROR;
      }
      *fortran_order = 0;
      sawFortranOrder = 1;
    } else if (strncmp((char *)key, "'shape'", strlen("'shape'")) == 0) {
      // "(xxx, xxx)" OR (xxx,)
      size_t first;
      rc = npy_scanner_next(&scanner, &token);
      if ((rc != VEC0_TOKEN_RESULT_SOME) ||
          (token.token_type != NPY_TOKEN_TYPE_LPAREN)) {
        vtab_set_error(pVTab, NPY_PARSE_ERROR
                       "Expected left parenthesis '(' after shape key");
        return SQLITE_ERROR;
      }

      rc = npy_scanner_next(&scanner, &token);
      if ((rc != VEC0_TOKEN_RESULT_SOME) ||
          (token.token_type != NPY_TOKEN_TYPE_NUMBER)) {
        vtab_set_error(pVTab, NPY_PARSE_ERROR
                       "Expected an initial number in shape value");
        return SQLITE_ERROR;
      }
      first = npy_token_to_size(&token);

      rc = npy_scanner_next(&scanner, &token);
      if ((rc != VEC0_TOKEN_RESULT_SOME) ||
          (token.token_type != NPY_TOKEN_TYPE_COMMA)) {
        vtab_set_error(pVTab, NPY_PARSE_ERROR
                       "Expected comma after first shape value");
        return SQLITE_ERROR;
      }

      rc = npy_scanner_next(&scanner, &token);
      if (rc != VEC0_TOKEN_RESULT_SOME) {
        vtab_set_error(pVTab, NPY_PARSE_ERROR
                       "unexpected header EOF while parsing shape");
        return SQLITE_ERROR;
      }
      if (token.token_type == NPY_TOKEN_TYPE_NUMBER) {
        *numElements = first;
        *numDimensions = npy_token_to_size(&token);
        rc = npy_scanner_next(&scanner, &token);
        if ((rc != VEC0_TOKEN_RESULT_SOME) ||
            (token.token_type != NPY_TOKEN_TYPE_RPAREN)) {
          vtab_set_error(pVTab, NPY_PARSE_ERROR
                         "expected right parenthesis after shape value");
          return SQLITE_ERROR;
        }
      } else if (token.token_type == NPY_TOKEN_TYPE_RPAREN) {
        // '(0,)' means an empty array!
        *numElements = first ? 1 : 0;
        *numDimensions = first;
      } else {
        vtab_set_error(pVTab, NPY_PARSE_ERROR "unknown type in shape value");
        return SQLITE_ERROR;
      }
      sawShape = 1;
    } else {
      vtab_set_error(pVTab, NPY_PARSE_ERROR "unknown key in numpy header");
      return SQLITE_ERROR;
    }

    rc = npy_scanner_next(&scanner, &token);
    if ((rc != VEC0_TOKEN_RESULT_SOME) ||
        (token.token_type != NPY_TOKEN_TYPE_COMMA)) {
      vtab_set_error(pVTab, NPY_PARSE_ERROR "unknown extra token after value");
      return SQLITE_ERROR;
    }
  }

  // all three keys are mandatory in the npy format; without them the out
  // parameters would be left uninitialized
  if (!sawDescr || !sawFortranOrder || !sawShape) {
    vtab_set_error(pVTab, NPY_PARSE_ERROR
                   "numpy header missing 'descr', 'fortran_order', or 'shape'");
    return SQLITE_ERROR;
  }

  return SQLITE_OK;
}

typedef struct vec_npy_each_vtab vec_npy_each_vtab;
struct vec_npy_each_vtab {
  sqlite3_vtab base;
};

typedef enum {
  VEC_NPY_EACH_INPUT_BUFFER,
  VEC_NPY_EACH_INPUT_FILE,
} vec_npy_each_input_type;

typedef struct vec_npy_each_cursor vec_npy_each_cursor;
struct vec_npy_each_cursor {
  sqlite3_vtab_cursor base;
  i64 iRowid;
  // sqlite-vec compatible type of vector
  enum VectorElementType elementType;
  // number of vectors in the npy array
  size_t nElements;
  // number of dimensions each vector has
  size_t nDimensions;

  vec_npy_each_input_type input_type;

  // when input_type == VEC_NPY_EACH_INPUT_BUFFER

  // Buffer containing the vector data, when reading from an in-memory buffer.
  // Size: nElements * nDimensions * element_size
  // Clean up with sqlite3_free() once complete
  void *vector;

  // when input_type == VEC_NPY_EACH_INPUT_FILE

  // Opened npy file, when reading from a file.
  // fclose() when complete.
#ifndef SQLITE_VEC_OMIT_FS
  FILE *file;
#endif

  // an in-memory buffer containing a portion of the npy array.
  // Used for faster reading, instead of calling fread a lot.
  // Will have a byte-size of fileBufferSize
  void *chunksBuffer;
  // size of allocated fileBuffer in bytes
  size_t chunksBufferSize;
  //// Maximum length of the buffer, in terms of number of vectors.
  size_t maxChunks;

  // Counter index of the current vector into of fileBuffer to yield.
  // Starts at 0 once fileBuffer is read, and iterates to bufferLength.
  // Resets to 0 once that "buffer" is yielded and a new one is read.
  size_t currentChunkIndex;
  size_t currentChunkSize;

  // 0 when there are still more elements to read/yield, 1 when complete.
  int eof;
};

static unsigned char NPY_MAGIC[6] = {0x93, 'N', 'U', 'M', 'P', 'Y'};

// Sets *out to the byte size of numElements float32 vectors of numDimensions
// elements each. Returns 0 if that size does not fit in a size_t.
static int npy_data_size(size_t numElements, size_t numDimensions,
                         size_t *out) {
  if (numElements && numDimensions > SIZE_MAX / sizeof(f32) / numElements) {
    return 0;
  }
  *out = numElements * numDimensions * sizeof(f32);
  return 1;
}

#ifndef SQLITE_VEC_OMIT_FS
int parse_npy_file(sqlite3_vtab *pVTab, FILE *file, vec_npy_each_cursor *pCur) {
  int n;
#ifdef _WIN32
  int seekResult = _fseeki64(file, 0, SEEK_END);
  sqlite3_int64 fileSize = _ftelli64(file);
  int rewindResult = _fseeki64(file, 0, SEEK_SET);
#else
  int seekResult = fseeko(file, 0, SEEK_END);
  sqlite3_int64 fileSize = ftello(file);
  int rewindResult = fseeko(file, 0, SEEK_SET);
#endif
  if (seekResult != 0 || fileSize < 0 || rewindResult != 0) {
    vtab_set_error(pVTab, "Could not determine numpy file size");
    return SQLITE_ERROR;
  }

  unsigned char header[10];
  n = fread(&header, sizeof(unsigned char), 10, file);
  if (n != 10) {
    vtab_set_error(pVTab, "numpy array file too short");
    return SQLITE_ERROR;
  }

  if (memcmp(NPY_MAGIC, header, sizeof(NPY_MAGIC)) != 0) {
    vtab_set_error(pVTab,
                   "numpy array file does not contain the 'magic' header");
    return SQLITE_ERROR;
  }

  u8 major = header[6];
  u8 minor = header[7];
  uint16_t headerLength = 0;
  memcpy(&headerLength, &header[8], sizeof(uint16_t));

  size_t totalHeaderLength = sizeof(NPY_MAGIC) + sizeof(major) + sizeof(minor) +
                             sizeof(headerLength) + headerLength;
  if ((sqlite3_uint64)fileSize < totalHeaderLength) {
    vtab_set_error(pVTab, "numpy array file header length is invalid");
    return SQLITE_ERROR;
  }
  sqlite3_uint64 dataSize = (sqlite3_uint64)fileSize - totalHeaderLength;

  unsigned char *headerX = sqlite3_malloc(headerLength);
  if (headerLength && !headerX) {
    return SQLITE_NOMEM;
  }

  n = fread(headerX, sizeof(char), headerLength, file);
  if (n != headerLength) {
    sqlite3_free(headerX);
    vtab_set_error(pVTab, "numpy array file header length is invalid");
    return SQLITE_ERROR;
  }

  int fortran_order;
  enum VectorElementType element_type;
  size_t numElements;
  size_t numDimensions;
  int rc = parse_npy_header(pVTab, headerX, headerLength, &element_type,
                            &fortran_order, &numElements, &numDimensions);
  sqlite3_free(headerX);
  if (rc != SQLITE_OK) {
    // parse_npy_header already attackes an error emssage
    return rc;
  }

  size_t expectedDataSize;
  if (!npy_data_size(numElements, numDimensions, &expectedDataSize)) {
    vtab_set_error(pVTab, "numpy array file error: shape is too large");
    return SQLITE_ERROR;
  }
  if (expectedDataSize != dataSize) {
    vtab_set_error(
        pVTab,
        "numpy array file error: Expected a data size of %llu, found %llu",
        (sqlite3_uint64)expectedDataSize, (sqlite3_uint64)dataSize);
    return SQLITE_ERROR;
  }

  pCur->maxChunks = numElements < 1024 ? numElements : 1024;
  pCur->chunksBufferSize =
      (vector_byte_size(element_type, numDimensions)) * pCur->maxChunks;
  pCur->chunksBuffer = sqlite3_malloc64(pCur->chunksBufferSize);
  if (pCur->chunksBufferSize && !pCur->chunksBuffer) {
    return SQLITE_NOMEM;
  }

  pCur->currentChunkSize =
      fread(pCur->chunksBuffer, vector_byte_size(element_type, numDimensions),
            pCur->maxChunks, file);

  pCur->currentChunkIndex = 0;
  pCur->elementType = element_type;
  pCur->nElements = numElements;
  pCur->nDimensions = numDimensions;
  pCur->input_type = VEC_NPY_EACH_INPUT_FILE;

  pCur->eof = pCur->currentChunkSize == 0;
  pCur->file = file;
  return SQLITE_OK;
}
#endif

int parse_npy_buffer(sqlite3_vtab *pVTab, const unsigned char *buffer,
                     int bufferLength, void **data, size_t *numElements,
                     size_t *numDimensions,
                     enum VectorElementType *element_type) {

  if (bufferLength < 10) {
    // IMP: V03312_20150
    vtab_set_error(pVTab, "numpy array too short");
    return SQLITE_ERROR;
  }
  if (memcmp(NPY_MAGIC, buffer, sizeof(NPY_MAGIC)) != 0) {
    // V11954_28792
    vtab_set_error(pVTab, "numpy array does not contain the 'magic' header");
    return SQLITE_ERROR;
  }

  u8 major = buffer[6];
  u8 minor = buffer[7];
  uint16_t headerLength = 0;
  memcpy(&headerLength, &buffer[8], sizeof(uint16_t));

  i32 totalHeaderLength = sizeof(NPY_MAGIC) + sizeof(major) + sizeof(minor) +
                          sizeof(headerLength) + headerLength;
  i32 dataSize = bufferLength - totalHeaderLength;

  if (dataSize < 0) {
    vtab_set_error(pVTab, "numpy array header length is invalid");
    return SQLITE_ERROR;
  }

  const unsigned char *header = &buffer[10];
  int fortran_order;

  int rc = parse_npy_header(pVTab, header, headerLength, element_type,
                            &fortran_order, numElements, numDimensions);
  if (rc != SQLITE_OK) {
    return rc;
  }

  size_t expectedDataSize;
  if (!npy_data_size(*numElements, *numDimensions, &expectedDataSize)) {
    vtab_set_error(pVTab, "numpy array error: shape is too large");
    return SQLITE_ERROR;
  }
  if (expectedDataSize != (size_t)dataSize) {
    vtab_set_error(pVTab,
                   "numpy array error: Expected a data size of %llu, found %d",
                   (sqlite3_uint64)expectedDataSize, dataSize);
    return SQLITE_ERROR;
  }

  *data = (void *)&buffer[totalHeaderLength];
  return SQLITE_OK;
}

static int vec_npy_eachConnect(sqlite3 *db, void *pAux, int argc,
                               const char *const *argv, sqlite3_vtab **ppVtab,
                               char **pzErr) {
  UNUSED_PARAMETER(pAux);
  UNUSED_PARAMETER(argc);
  UNUSED_PARAMETER(argv);
  UNUSED_PARAMETER(pzErr);
  vec_npy_each_vtab *pNew;
  int rc;

  rc = sqlite3_declare_vtab(db, "CREATE TABLE x(vector, input hidden)");
#define VEC_NPY_EACH_COLUMN_VECTOR 0
#define VEC_NPY_EACH_COLUMN_INPUT 1
  if (rc == SQLITE_OK) {
    pNew = sqlite3_malloc(sizeof(*pNew));
    *ppVtab = (sqlite3_vtab *)pNew;
    if (pNew == 0)
      return SQLITE_NOMEM;
    memset(pNew, 0, sizeof(*pNew));
  }
  return rc;
}

static int vec_npy_eachDisconnect(sqlite3_vtab *pVtab) {
  vec_npy_each_vtab *p = (vec_npy_each_vtab *)pVtab;
  sqlite3_free(p);
  return SQLITE_OK;
}

static int vec_npy_eachOpen(sqlite3_vtab *p, sqlite3_vtab_cursor **ppCursor) {
  UNUSED_PARAMETER(p);
  vec_npy_each_cursor *pCur;
  pCur = sqlite3_malloc(sizeof(*pCur));
  if (pCur == 0)
    return SQLITE_NOMEM;
  memset(pCur, 0, sizeof(*pCur));
  *ppCursor = &pCur->base;
  return SQLITE_OK;
}

static int vec_npy_eachClose(sqlite3_vtab_cursor *cur) {
  vec_npy_each_cursor *pCur = (vec_npy_each_cursor *)cur;
#ifndef SQLITE_VEC_OMIT_FS
  if (pCur->file) {
    fclose(pCur->file);
    pCur->file = NULL;
  }
#endif
  if (pCur->chunksBuffer) {
    sqlite3_free(pCur->chunksBuffer);
    pCur->chunksBuffer = NULL;
  }
  if (pCur->vector) {
    pCur->vector = NULL;
  }
  sqlite3_free(pCur);
  return SQLITE_OK;
}

static int vec_npy_eachBestIndex(sqlite3_vtab *pVTab,
                                 sqlite3_index_info *pIdxInfo) {
  int hasInput;
  for (int i = 0; i < pIdxInfo->nConstraint; i++) {
    const struct sqlite3_index_constraint *pCons = &pIdxInfo->aConstraint[i];
    // printf("i=%d iColumn=%d, op=%d, usable=%d\n", i, pCons->iColumn,
    // pCons->op, pCons->usable);
    switch (pCons->iColumn) {
    case VEC_NPY_EACH_COLUMN_INPUT: {
      if (pCons->op == SQLITE_INDEX_CONSTRAINT_EQ && pCons->usable) {
        hasInput = 1;
        pIdxInfo->aConstraintUsage[i].argvIndex = 1;
        pIdxInfo->aConstraintUsage[i].omit = 1;
      }
      break;
    }
    }
  }
  if (!hasInput) {
    pVTab->zErrMsg = sqlite3_mprintf("input argument is required");
    return SQLITE_ERROR;
  }

  pIdxInfo->estimatedCost = (double)100000;
  pIdxInfo->estimatedRows = 100000;

  return SQLITE_OK;
}

static int vec_npy_eachFilter(sqlite3_vtab_cursor *pVtabCursor, int idxNum,
                              const char *idxStr, int argc,
                              sqlite3_value **argv) {
  UNUSED_PARAMETER(idxNum);
  UNUSED_PARAMETER(idxStr);
  assert(argc == 1);
  int rc;

  vec_npy_each_cursor *pCur = (vec_npy_each_cursor *)pVtabCursor;

#ifndef SQLITE_VEC_OMIT_FS
  if (pCur->file) {
    fclose(pCur->file);
    pCur->file = NULL;
  }
#endif
  if (pCur->chunksBuffer) {
    sqlite3_free(pCur->chunksBuffer);
    pCur->chunksBuffer = NULL;
  }
  if (pCur->vector) {
    pCur->vector = NULL;
  }

#ifndef SQLITE_VEC_OMIT_FS
  struct VecNpyFile *f = NULL;
  if ((f = sqlite3_value_pointer(argv[0], SQLITE_VEC_NPY_FILE_NAME))) {
    FILE *file = fopen(f->path, "rb");
    if (!file) {
      vtab_set_error(pVtabCursor->pVtab, "Could not open numpy file");
      return SQLITE_ERROR;
    }

    rc = parse_npy_file(pVtabCursor->pVtab, file, pCur);
    if (rc != SQLITE_OK) {
#ifndef SQLITE_VEC_OMIT_FS
      fclose(file);
#endif
      return rc;
    }

  } else
#endif
  {

    const unsigned char *input = sqlite3_value_blob(argv[0]);
    int inputLength = sqlite3_value_bytes(argv[0]);
    void *data;
    size_t numElements;
    size_t numDimensions;
    enum VectorElementType element_type;

    rc = parse_npy_buffer(pVtabCursor->pVtab, input, inputLength, &data,
                          &numElements, &numDimensions, &element_type);
    if (rc != SQLITE_OK) {
      return rc;
    }

    pCur->vector = data;
    pCur->elementType = element_type;
    pCur->nElements = numElements;
    pCur->nDimensions = numDimensions;
    pCur->input_type = VEC_NPY_EACH_INPUT_BUFFER;
  }

  pCur->iRowid = 0;
  return SQLITE_OK;
}

static int vec_npy_eachRowid(sqlite3_vtab_cursor *cur, sqlite_int64 *pRowid) {
  vec_npy_each_cursor *pCur = (vec_npy_each_cursor *)cur;
  *pRowid = pCur->iRowid;
  return SQLITE_OK;
}

static int vec_npy_eachEof(sqlite3_vtab_cursor *cur) {
  vec_npy_each_cursor *pCur = (vec_npy_each_cursor *)cur;
  if (pCur->input_type == VEC_NPY_EACH_INPUT_BUFFER) {
    return (!pCur->nElements) || (size_t)pCur->iRowid >= pCur->nElements;
  }
  return pCur->eof;
}

static int vec_npy_eachNext(sqlite3_vtab_cursor *cur) {
  vec_npy_each_cursor *pCur = (vec_npy_each_cursor *)cur;
  pCur->iRowid++;
  if (pCur->input_type == VEC_NPY_EACH_INPUT_BUFFER) {
    return SQLITE_OK;
  }

#ifndef SQLITE_VEC_OMIT_FS
  // else: input is a file
  pCur->currentChunkIndex++;
  if (pCur->currentChunkIndex >= pCur->currentChunkSize) {
    pCur->currentChunkSize =
        fread(pCur->chunksBuffer,
              vector_byte_size(pCur->elementType, pCur->nDimensions),
              pCur->maxChunks, pCur->file);
    if (!pCur->currentChunkSize) {
      pCur->eof = 1;
    }
    pCur->currentChunkIndex = 0;
  }
#endif
  return SQLITE_OK;
}

static int vec_npy_eachColumnBuffer(vec_npy_each_cursor *pCur,
                                    sqlite3_context *context, int i) {
  switch (i) {
  case VEC_NPY_EACH_COLUMN_VECTOR: {
    sqlite3_result_subtype(context, pCur->elementType);
    switch (pCur->elementType) {
    case SQLITE_VEC_ELEMENT_TYPE_FLOAT32: {
      sqlite3_result_blob(
          context,
          &((unsigned char *)
                pCur->vector)[pCur->iRowid * pCur->nDimensions * sizeof(f32)],
          pCur->nDimensions * sizeof(f32), SQLITE_TRANSIENT);

      break;
    }
    case SQLITE_VEC_ELEMENT_TYPE_INT8:
    case SQLITE_VEC_ELEMENT_TYPE_BIT: {
      // https://github.com/asg017/sqlite-vec/issues/42
      sqlite3_result_error(context,
                           "vec_npy_each only supports float32 vectors", -1);
      break;
    }
    }

    break;
  }
  }
  return SQLITE_OK;
}
static int vec_npy_eachColumnFile(vec_npy_each_cursor *pCur,
                                  sqlite3_context *context, int i) {
  switch (i) {
  case VEC_NPY_EACH_COLUMN_VECTOR: {
    switch (pCur->elementType) {
    case SQLITE_VEC_ELEMENT_TYPE_FLOAT32: {
      sqlite3_result_blob(
          context,
          &((unsigned char *)
                pCur->chunksBuffer)[pCur->currentChunkIndex *
                                    pCur->nDimensions * sizeof(f32)],
          pCur->nDimensions * sizeof(f32), SQLITE_TRANSIENT);
      break;
    }
    case SQLITE_VEC_ELEMENT_TYPE_INT8:
    case SQLITE_VEC_ELEMENT_TYPE_BIT: {
      // https://github.com/asg017/sqlite-vec/issues/42
      sqlite3_result_error(context,
                           "vec_npy_each only supports float32 vectors", -1);
      break;
    }
    }
    break;
  }
  }
  return SQLITE_OK;
}
static int vec_npy_eachColumn(sqlite3_vtab_cursor *cur,
                              sqlite3_context *context, int i) {
  vec_npy_each_cursor *pCur = (vec_npy_each_cursor *)cur;
  switch (pCur->input_type) {
  case VEC_NPY_EACH_INPUT_BUFFER:
    return vec_npy_eachColumnBuffer(pCur, context, i);
  case VEC_NPY_EACH_INPUT_FILE:
    return vec_npy_eachColumnFile(pCur, context, i);
  }
  return SQLITE_ERROR;
}

static sqlite3_module vec_npy_eachModule = {
    /* iVersion    */ 0,
    /* xCreate     */ 0,
    /* xConnect    */ vec_npy_eachConnect,
    /* xBestIndex  */ vec_npy_eachBestIndex,
    /* xDisconnect */ vec_npy_eachDisconnect,
    /* xDestroy    */ 0,
    /* xOpen       */ vec_npy_eachOpen,
    /* xClose      */ vec_npy_eachClose,
    /* xFilter     */ vec_npy_eachFilter,
    /* xNext       */ vec_npy_eachNext,
    /* xEof        */ vec_npy_eachEof,
    /* xColumn     */ vec_npy_eachColumn,
    /* xRowid      */ vec_npy_eachRowid,
    /* xUpdate     */ 0,
    /* xBegin      */ 0,
    /* xSync       */ 0,
    /* xCommit     */ 0,
    /* xRollback   */ 0,
    /* xFindMethod */ 0,
    /* xRename     */ 0,
    /* xSavepoint  */ 0,
    /* xRelease    */ 0,
    /* xRollbackTo */ 0,
    /* xShadowName */ 0,
#if SQLITE_VERSION_NUMBER >= 3044000
    /* xIntegrity  */ 0,
#endif
};

#pragma endregion

#pragma region vec0 virtual table

#define VEC0_COLUMN_ID 0
#define VEC0_COLUMN_USERN_START 1
#define VEC0_COLUMN_OFFSET_DISTANCE 1
#define VEC0_COLUMN_OFFSET_K 2
#define VEC0_COLUMN_OFFSET_TABLE_NAME 3
#define VEC0_COLUMN_OFFSET_MMR_LAMBDA 4

#define VEC0_SHADOW_INFO_NAME "\"%w\".\"%w_info\""

#define VEC0_SHADOW_CHUNKS_NAME "\"%w\".\"%w_chunks\""
/// 1) schema, 2) original vtab table name
#define VEC0_SHADOW_CHUNKS_CREATE                                              \
  "CREATE TABLE " VEC0_SHADOW_CHUNKS_NAME "("                                  \
  "chunk_id INTEGER PRIMARY KEY AUTOINCREMENT,"                                \
  "size INTEGER NOT NULL,"                                                     \
  "validity BLOB NOT NULL,"                                                    \
  "rowids BLOB NOT NULL"                                                       \
  ");"

#define VEC0_SHADOW_ROWIDS_NAME "\"%w\".\"%w_rowids\""
/// 1) schema, 2) original vtab table name
#define VEC0_SHADOW_ROWIDS_CREATE_BASIC                                        \
  "CREATE TABLE " VEC0_SHADOW_ROWIDS_NAME "("                                  \
  "rowid INTEGER PRIMARY KEY AUTOINCREMENT,"                                   \
  "id,"                                                                        \
  "chunk_id INTEGER,"                                                          \
  "chunk_offset INTEGER"                                                       \
  ");"

// vec0 tables with a text primary keys are still backed by int64 primary keys,
// since a fixed-length rowid is required for vec0 chunks. But we add a new 'id
// text unique' column to emulate a text primary key interface.
#define VEC0_SHADOW_ROWIDS_CREATE_PK_TEXT                                      \
  "CREATE TABLE " VEC0_SHADOW_ROWIDS_NAME "("                                  \
  "rowid INTEGER PRIMARY KEY AUTOINCREMENT,"                                   \
  "id TEXT UNIQUE NOT NULL,"                                                   \
  "chunk_id INTEGER,"                                                          \
  "chunk_offset INTEGER"                                                       \
  ");"

/// 1) schema, 2) original vtab table name
#define VEC0_SHADOW_VECTOR_N_NAME "\"%w\".\"%w_vector_chunks%02d\""

/// 1) schema, 2) original vtab table name
#define VEC0_SHADOW_VECTOR_N_CREATE                                            \
  "CREATE TABLE " VEC0_SHADOW_VECTOR_N_NAME "("                                \
  "rowid INTEGER PRIMARY KEY,"                                                 \
  "vectors BLOB NOT NULL"                                                      \
  ");"

#define VEC0_SHADOW_AUXILIARY_NAME "\"%w\".\"%w_auxiliary\""

#define VEC0_SHADOW_METADATA_N_NAME "\"%w\".\"%w_metadatachunks%02d\""
#define VEC0_SHADOW_METADATA_TEXT_DATA_NAME "\"%w\".\"%w_metadatatext%02d\""

#define VEC_INTERAL_ERROR "Internal sqlite-vec error: "
#define REPORT_URL "https://github.com/asg017/sqlite-vec/issues/new"

typedef struct vec0_vtab vec0_vtab;

#define VEC0_MAX_VECTOR_COLUMNS 16
#define VEC0_MAX_PARTITION_COLUMNS 4
#define VEC0_MAX_AUXILIARY_COLUMNS 16
#define VEC0_MAX_METADATA_COLUMNS 16

#define SQLITE_VEC_VEC0_MAX_DIMENSIONS 8192
#define VEC0_METADATA_TEXT_VIEW_BUFFER_LENGTH 16
#define VEC0_METADATA_TEXT_VIEW_DATA_LENGTH 12

typedef enum {
  // vector column, ie "contents_embedding float[1024]"
  SQLITE_VEC0_USER_COLUMN_KIND_VECTOR = 1,

  // partition key column, ie "user_id integer partition key"
  SQLITE_VEC0_USER_COLUMN_KIND_PARTITION = 2,

  //
  SQLITE_VEC0_USER_COLUMN_KIND_AUXILIARY = 3,

  // metadata column that can be filtered, ie "genre text"
  SQLITE_VEC0_USER_COLUMN_KIND_METADATA = 4,
} vec0_user_column_kind;

struct vec0_vtab {
  sqlite3_vtab base;

  // the SQLite connection of the host database
  sqlite3 *db;

  // True if the primary key of the vec0 table has a column type TEXT.
  // Will change the schema of the _rowids table, and insert/query logic.
  int pkIsText;

  // The database's text encoding, SQLITE_UTF8, SQLITE_UTF16LE or
  // SQLITE_UTF16BE. vec0 keeps text metadata as UTF-8, and SQLite orders text
  // under BINARY by the bytes of the database's encoding.
  int textEncoding;

  // True if the table declares the hidden command column named after the
  // table, which runs `INSERT INTO t(t) VALUES ('optimize')`. False when
  // another column has the table's name; see vec0_init().
  int hasCommandColumn;

  // number of defined vector columns.
  int numVectorColumns;

  // number of defined PARTITION KEY columns.
  int numPartitionColumns;

  // number of defined auxiliary columns
  int numAuxiliaryColumns;

  // number of defined metadata columns
  int numMetadataColumns;

  // Name of the schema the table exists on.
  // Must be freed with sqlite3_free()
  char *schemaName;

  // Name of the table the table exists on.
  // Must be freed with sqlite3_free()
  char *tableName;

  // Name of the _rowids shadow table.
  // Must be freed with sqlite3_free()
  char *shadowRowidsName;

  // Name of the _chunks shadow table.
  // Must be freed with sqlite3_free()
  char *shadowChunksName;

  // contains enum vec0_user_column_kind values for up to
  // numVectorColumns + numPartitionColumns entries
  vec0_user_column_kind
      user_column_kinds[VEC0_MAX_VECTOR_COLUMNS + VEC0_MAX_PARTITION_COLUMNS +
                        VEC0_MAX_AUXILIARY_COLUMNS + VEC0_MAX_METADATA_COLUMNS];

  uint8_t
      user_column_idxs[VEC0_MAX_VECTOR_COLUMNS + VEC0_MAX_PARTITION_COLUMNS +
                       VEC0_MAX_AUXILIARY_COLUMNS + VEC0_MAX_METADATA_COLUMNS];

  // Name of all the vector chunk shadow tables.
  // Ex '_vector_chunks00'
  // Only the first numVectorColumns entries will be available.
  // The first numVectorColumns entries must be freed with sqlite3_free()
  char *shadowVectorChunksNames[VEC0_MAX_VECTOR_COLUMNS];

  // Name of all metadata chunk shadow tables, ie `_metadatachunks00`
  // Only the first numMetadataColumns entries will be available.
  // The first numMetadataColumns entries must be freed with sqlite3_free()
  char *shadowMetadataChunksNames[VEC0_MAX_METADATA_COLUMNS];

  struct VectorColumnDefinition vector_columns[VEC0_MAX_VECTOR_COLUMNS];
  struct Vec0PartitionColumnDefinition
      paritition_columns[VEC0_MAX_PARTITION_COLUMNS];
  struct Vec0AuxiliaryColumnDefinition
      auxiliary_columns[VEC0_MAX_AUXILIARY_COLUMNS];
  struct Vec0MetadataColumnDefinition
      metadata_columns[VEC0_MAX_METADATA_COLUMNS];

  int chunk_size;

  // select latest chunk from _chunks, getting chunk_id
  sqlite3_stmt *stmtLatestChunk;

  /**
   * Statement to insert a row into the _rowids table, with a rowid.
   * Parameters:
   *    1: int64, rowid to insert
   * Result columns: none
   * SQL: "INSERT INTO _rowids(rowid) VALUES (?)"
   *
   * Must be cleaned up with sqlite3_finalize().
   */
  sqlite3_stmt *stmtRowidsInsertRowid;

  /**
   * Statement to insert a row into the _rowids table, with an id.
   * The id column isn't a tradition primary key, but instead a unique
   * column to handle "text primary key" vec0 tables. The true int64 rowid
   * can be retrieved after inserting with sqlite3_last_rowid().
   *
   * Parameters:
   *    1: text or null, id to insert
   * Result columns: none
   *
   * Must be cleaned up with sqlite3_finalize().
   */
  sqlite3_stmt *stmtRowidsInsertId;

  /**
   * Statement to update the "position" columns chunk_id and chunk_offset for
   * a given _rowids row. Used when the "next available" chunk position is found
   * for a vector.
   *
   * Parameters:
   *    1: int64, chunk_id value
   *    2: int64, chunk_offset value
   *    3: int64, rowid value
   * Result columns: none
   *
   * Must be cleaned up with sqlite3_finalize().
   */
  sqlite3_stmt *stmtRowidsUpdatePosition;

  /**
   * Statement to quickly find the chunk_id + chunk_offset of a given row.
   * Parameters:
   *  1: rowid of the row/vector to lookup
   * Result columns:
   *  0: chunk_id (i64)
   *  1: chunk_offset (i64)
   * SQL: "SELECT id, chunk_id, chunk_offset FROM _rowids WHERE rowid = ?""
   *
   * Must be cleaned up with sqlite3_finalize().
   */
  sqlite3_stmt *stmtRowidsGetChunkPosition;
};

/**
 * @brief Finalize all the sqlite3_stmt members in a vec0_vtab.
 *
 * @param p vec0_vtab pointer
 */
void vec0_free_resources(vec0_vtab *p) {
  sqlite3_finalize(p->stmtLatestChunk);
  p->stmtLatestChunk = NULL;
  sqlite3_finalize(p->stmtRowidsInsertRowid);
  p->stmtRowidsInsertRowid = NULL;
  sqlite3_finalize(p->stmtRowidsInsertId);
  p->stmtRowidsInsertId = NULL;
  sqlite3_finalize(p->stmtRowidsUpdatePosition);
  p->stmtRowidsUpdatePosition = NULL;
  sqlite3_finalize(p->stmtRowidsGetChunkPosition);
  p->stmtRowidsGetChunkPosition = NULL;
}

/**
 * @brief Free a vec0_vtab and all its resources.
 *
 * Frees all internal allocations (strings, statements) and the struct itself.
 *
 * @param p vec0_vtab pointer
 */
void vec0_free(vec0_vtab *p) {
  vec0_free_resources(p);

  sqlite3_free(p->schemaName);
  p->schemaName = NULL;
  sqlite3_free(p->tableName);
  p->tableName = NULL;
  sqlite3_free(p->shadowChunksName);
  p->shadowChunksName = NULL;
  sqlite3_free(p->shadowRowidsName);
  p->shadowRowidsName = NULL;

  for (int i = 0; i < p->numVectorColumns; i++) {
    sqlite3_free(p->shadowVectorChunksNames[i]);
    p->shadowVectorChunksNames[i] = NULL;
    sqlite3_free(p->vector_columns[i].name);
    p->vector_columns[i].name = NULL;
  }
  for (int i = 0; i < p->numPartitionColumns; i++) {
    sqlite3_free(p->paritition_columns[i].name);
    p->paritition_columns[i].name = NULL;
  }
  for (int i = 0; i < p->numAuxiliaryColumns; i++) {
    sqlite3_free(p->auxiliary_columns[i].name);
    p->auxiliary_columns[i].name = NULL;
  }
  for (int i = 0; i < p->numMetadataColumns; i++) {
    sqlite3_free(p->shadowMetadataChunksNames[i]);
    p->shadowMetadataChunksNames[i] = NULL;
    sqlite3_free(p->metadata_columns[i].name);
    p->metadata_columns[i].name = NULL;
  }

  sqlite3_free(p);
}

int vec0_num_defined_user_columns(vec0_vtab *p) {
  return p->numVectorColumns + p->numPartitionColumns + p->numAuxiliaryColumns +
         p->numMetadataColumns;
}

/**
 * @brief Returns the index of the distance hidden column for the given vec0
 * table.
 *
 * @param p vec0 table
 * @return int
 */
int vec0_column_distance_idx(vec0_vtab *p) {
  return VEC0_COLUMN_USERN_START + (vec0_num_defined_user_columns(p) - 1) +
         VEC0_COLUMN_OFFSET_DISTANCE;
}

/**
 * @brief Returns the index of the k hidden column for the given vec0 table.
 *
 * @param p vec0 table
 * @return int k column index
 */
int vec0_column_k_idx(vec0_vtab *p) {
  return VEC0_COLUMN_USERN_START + (vec0_num_defined_user_columns(p) - 1) +
         VEC0_COLUMN_OFFSET_K;
}

/**
 * @brief Returns the index of the table_name hidden column for the given vec0
 * table. ONLY call if p->hasCommandColumn.
 *
 * @param p vec0 table
 * @return int
 */
int vec0_column_table_name_idx(vec0_vtab *p) {
  return VEC0_COLUMN_USERN_START + (vec0_num_defined_user_columns(p) - 1) +
         VEC0_COLUMN_OFFSET_TABLE_NAME;
}

/**
 * Returns the column index for the hidden "mmr_lambda" column, which follows
 * the table_name column when the table has one.
 */
int vec0_column_mmr_lambda_idx(vec0_vtab *p) {
  return VEC0_COLUMN_USERN_START + (vec0_num_defined_user_columns(p) - 1) +
         VEC0_COLUMN_OFFSET_MMR_LAMBDA - (p->hasCommandColumn ? 0 : 1);
}

/**
 * Returns 1 if the given column-based index is a valid vector column,
 * 0 otherwise.
 */
int vec0_column_idx_is_vector(vec0_vtab *pVtab, int column_idx) {
  return column_idx >= VEC0_COLUMN_USERN_START &&
         column_idx <= (VEC0_COLUMN_USERN_START +
                        vec0_num_defined_user_columns(pVtab) - 1) &&
         pVtab->user_column_kinds[column_idx - VEC0_COLUMN_USERN_START] ==
             SQLITE_VEC0_USER_COLUMN_KIND_VECTOR;
}

/**
 * Returns the vector index of the given user column index.
 * ONLY call if validated with vec0_column_idx_is_vector before
 */
int vec0_column_idx_to_vector_idx(vec0_vtab *pVtab, int column_idx) {
  UNUSED_PARAMETER(pVtab);
  return pVtab->user_column_idxs[column_idx - VEC0_COLUMN_USERN_START];
}
/**
 * Returns 1 if the given column-based index is a "partition key" column,
 * 0 otherwise.
 */
int vec0_column_idx_is_partition(vec0_vtab *pVtab, int column_idx) {
  return column_idx >= VEC0_COLUMN_USERN_START &&
         column_idx <= (VEC0_COLUMN_USERN_START +
                        vec0_num_defined_user_columns(pVtab) - 1) &&
         pVtab->user_column_kinds[column_idx - VEC0_COLUMN_USERN_START] ==
             SQLITE_VEC0_USER_COLUMN_KIND_PARTITION;
}

/**
 * Returns the partition column index of the given user column index.
 * ONLY call if validated with vec0_column_idx_is_vector before
 */
int vec0_column_idx_to_partition_idx(vec0_vtab *pVtab, int column_idx) {
  UNUSED_PARAMETER(pVtab);
  return pVtab->user_column_idxs[column_idx - VEC0_COLUMN_USERN_START];
}

/**
 * Returns 1 if the given column-based index is a auxiliary column,
 * 0 otherwise.
 */
int vec0_column_idx_is_auxiliary(vec0_vtab *pVtab, int column_idx) {
  return column_idx >= VEC0_COLUMN_USERN_START &&
         column_idx <= (VEC0_COLUMN_USERN_START +
                        vec0_num_defined_user_columns(pVtab) - 1) &&
         pVtab->user_column_kinds[column_idx - VEC0_COLUMN_USERN_START] ==
             SQLITE_VEC0_USER_COLUMN_KIND_AUXILIARY;
}

/**
 * Returns the auxiliary column index of the given user column index.
 * ONLY call if validated with vec0_column_idx_to_partition_idx before
 */
int vec0_column_idx_to_auxiliary_idx(vec0_vtab *pVtab, int column_idx) {
  UNUSED_PARAMETER(pVtab);
  return pVtab->user_column_idxs[column_idx - VEC0_COLUMN_USERN_START];
}

/**
 * Returns 1 if the given column-based index is a metadata column,
 * 0 otherwise.
 */
int vec0_column_idx_is_metadata(vec0_vtab *pVtab, int column_idx) {
  return column_idx >= VEC0_COLUMN_USERN_START &&
         column_idx <= (VEC0_COLUMN_USERN_START +
                        vec0_num_defined_user_columns(pVtab) - 1) &&
         pVtab->user_column_kinds[column_idx - VEC0_COLUMN_USERN_START] ==
             SQLITE_VEC0_USER_COLUMN_KIND_METADATA;
}

/**
 * Returns the metadata column index of the given user column index.
 * ONLY call if validated with vec0_column_idx_is_metadata before
 */
int vec0_column_idx_to_metadata_idx(vec0_vtab *pVtab, int column_idx) {
  UNUSED_PARAMETER(pVtab);
  return pVtab->user_column_idxs[column_idx - VEC0_COLUMN_USERN_START];
}

/**
 * The result code for an internal statement or blob open that failed, or that
 * stepped to SQLITE_ROW or SQLITE_DONE where the other was expected:
 * SQLITE_INTERRUPT when sqlite3_interrupt() or a progress handler stopped it,
 * so the caller sees the interrupt, and SQLITE_ERROR otherwise.
 */
static int vec0_error_rc(int rc) {
  return rc == SQLITE_INTERRUPT ? SQLITE_INTERRUPT : SQLITE_ERROR;
}

/**
 * SQLite reports a virtual table's zErrMsg in place of the message for the
 * result code, so when a vec0 method was interrupted, drop the message vec0
 * set for the failure, and SQLite reports "interrupted".
 */
static int vec0_interrupt_result(sqlite3_vtab *pVTab, int rc) {
  if (rc == SQLITE_INTERRUPT) {
    sqlite3_free(pVTab->zErrMsg);
    pVTab->zErrMsg = NULL;
  }
  return rc;
}

/**
 * @brief Retrieve the chunk_id, chunk_offset, and possible "id" value
 * of a vec0_vtab row with the provided rowid
 *
 * @param p vec0_vtab
 * @param rowid the rowid of the row to query
 * @param id output, optional sqlite3_value to provide the id.
 *            Useful for text PK rows. Must be freed with sqlite3_value_free()
 * @param chunk_id output, the chunk_id the row belongs to
 * @param chunk_offset  output, the offset within the chunk the row belongs to
 * @return SQLITE_OK on success, SQLITE_EMPTY if the row does not exist, error
 * code otherwise
 */
int vec0_get_chunk_position(vec0_vtab *p, i64 rowid, sqlite3_value **id,
                            i64 *chunk_id, i64 *chunk_offset) {
  int rc;

  if (!p->stmtRowidsGetChunkPosition) {
    const char *zSql =
        sqlite3_mprintf("SELECT id, chunk_id, chunk_offset "
                        "FROM " VEC0_SHADOW_ROWIDS_NAME " WHERE rowid = ?",
                        p->schemaName, p->tableName);
    if (!zSql) {
      rc = SQLITE_NOMEM;
      goto cleanup;
    }
    rc = sqlite3_prepare_v2(p->db, zSql, -1, &p->stmtRowidsGetChunkPosition, 0);
    sqlite3_free((void *)zSql);
    if (rc != SQLITE_OK) {
      vtab_set_error(
          &p->base, VEC_INTERAL_ERROR
          "could not initialize 'rowids get chunk position' statement");
      goto cleanup;
    }
  }

  sqlite3_bind_int64(p->stmtRowidsGetChunkPosition, 1, rowid);
  rc = sqlite3_step(p->stmtRowidsGetChunkPosition);
  // special case: when no results, return SQLITE_EMPTY to convey "that chunk
  // position doesnt exist"
  if (rc == SQLITE_DONE) {
    rc = SQLITE_EMPTY;
    goto cleanup;
  }
  if (rc != SQLITE_ROW) {
    goto cleanup;
  }

  if (id) {
    sqlite3_value *value =
        sqlite3_column_value(p->stmtRowidsGetChunkPosition, 0);
    *id = sqlite3_value_dup(value);
    if (!*id) {
      rc = SQLITE_NOMEM;
      goto cleanup;
    }
  }

  if (chunk_id) {
    *chunk_id = sqlite3_column_int64(p->stmtRowidsGetChunkPosition, 1);
  }
  if (chunk_offset) {
    *chunk_offset = sqlite3_column_int64(p->stmtRowidsGetChunkPosition, 2);
  }

  rc = SQLITE_OK;

cleanup:
  if (p->stmtRowidsGetChunkPosition) {
    sqlite3_reset(p->stmtRowidsGetChunkPosition);
    sqlite3_clear_bindings(p->stmtRowidsGetChunkPosition);
  }
  return rc;
}

/**
 * @brief Return the id value from the _rowids table where _rowids.rowid =
 * rowid.
 *
 * @param pVtab: vec0 table to query
 * @param rowid: rowid of the row to query.
 * @param out: A dup'ed sqlite3_value of the id column. Might be null.
 *                         Must be cleaned up with sqlite3_value_free().
 * @returns SQLITE_OK on success, error code on failure
 */
int vec0_get_id_value_from_rowid(vec0_vtab *pVtab, i64 rowid,
                                 sqlite3_value **out) {
  // PERF: different strategy than get_chunk_position?
  return vec0_get_chunk_position((vec0_vtab *)pVtab, rowid, out, NULL, NULL);
}

int vec0_rowid_from_id(vec0_vtab *p, sqlite3_value *valueId, i64 *rowid) {
  sqlite3_stmt *stmt = NULL;
  int rc;
  char *zSql;
  zSql = sqlite3_mprintf("SELECT rowid"
                         " FROM " VEC0_SHADOW_ROWIDS_NAME " WHERE id = ?",
                         p->schemaName, p->tableName);
  if (!zSql) {
    rc = SQLITE_NOMEM;
    goto cleanup;
  }
  rc = sqlite3_prepare_v2(p->db, zSql, -1, &stmt, NULL);
  sqlite3_free(zSql);
  if (rc != SQLITE_OK) {
    goto cleanup;
  }
  sqlite3_bind_value(stmt, 1, valueId);
  rc = sqlite3_step(stmt);
  if (rc == SQLITE_DONE) {
    rc = SQLITE_EMPTY;
    goto cleanup;
  }
  if (rc != SQLITE_ROW) {
    goto cleanup;
  }
  *rowid = sqlite3_column_int64(stmt, 0);
  rc = sqlite3_step(stmt);
  if (rc != SQLITE_DONE) {
    goto cleanup;
  }

  rc = SQLITE_OK;

cleanup:
  sqlite3_finalize(stmt);
  return rc;
}

int vec0_result_id(vec0_vtab *p, sqlite3_context *context, i64 rowid) {
  if (!p->pkIsText) {
    sqlite3_result_int64(context, rowid);
    return SQLITE_OK;
  }
  sqlite3_value *valueId;
  int rc = vec0_get_id_value_from_rowid(p, rowid, &valueId);
  if (rc != SQLITE_OK) {
    return rc;
  }
  if (!valueId) {
    sqlite3_result_error_nomem(context);
  } else {
    sqlite3_result_value(context, valueId);
    sqlite3_value_free(valueId);
  }
  return SQLITE_OK;
}

/**
 * @brief
 *
 * @param pVtab: virtual table to query
 * @param rowid: row to lookup
 * @param vector_column_idx: which vector column to query
 * @param outVector: Output pointer to the vector buffer.
 *                    Must be sqlite3_free()'ed.
 * @param outVectorSize: Pointer to a int where the size of outVector
 *                       will be stored.
 * @return int SQLITE_OK on success.
 */
int vec0_get_vector_data(vec0_vtab *pVtab, i64 rowid, int vector_column_idx,
                         void **outVector, int *outVectorSize) {
  vec0_vtab *p = pVtab;
  int rc, brc;
  i64 chunk_id;
  i64 chunk_offset;
  size_t size;
  void *buf = NULL;
  int blobOffset;
  sqlite3_blob *vectorBlob = NULL;
  assert((vector_column_idx >= 0) &&
         (vector_column_idx < pVtab->numVectorColumns));

  rc = vec0_get_chunk_position(pVtab, rowid, NULL, &chunk_id, &chunk_offset);
  if (rc == SQLITE_EMPTY) {
    vtab_set_error(&pVtab->base, "Could not find a row with rowid %lld", rowid);
    goto cleanup;
  }
  if (rc != SQLITE_OK) {
    goto cleanup;
  }

  rc = sqlite3_blob_open(p->db, p->schemaName,
                         p->shadowVectorChunksNames[vector_column_idx],
                         "vectors", chunk_id, 0, &vectorBlob);

  if (rc != SQLITE_OK) {
    vtab_set_error(&pVtab->base,
                   "Could not fetch vector data for %lld, opening blob failed",
                   rowid);
    rc = vec0_error_rc(rc);
    goto cleanup;
  }

  size = vector_column_byte_size(pVtab->vector_columns[vector_column_idx]);
  blobOffset = chunk_offset * size;

  buf = sqlite3_malloc(size);
  if (!buf) {
    rc = SQLITE_NOMEM;
    goto cleanup;
  }

  rc = sqlite3_blob_read(vectorBlob, buf, size, blobOffset);
  if (rc != SQLITE_OK) {
    sqlite3_free(buf);
    buf = NULL;
    vtab_set_error(
        &pVtab->base,
        "Could not fetch vector data for %lld, reading from blob failed",
        rowid);
    rc = SQLITE_ERROR;
    goto cleanup;
  }

  *outVector = buf;
  if (outVectorSize) {
    *outVectorSize = size;
  }
  rc = SQLITE_OK;

cleanup:
  brc = sqlite3_blob_close(vectorBlob);
  if ((rc == SQLITE_OK) && (brc != SQLITE_OK)) {
    vtab_set_error(
        &p->base, VEC_INTERAL_ERROR
        "unknown error, could not close vector blob, please file an issue");
    return brc;
  }

  return rc;
}

/**
 * @brief Retrieve the sqlite3_value of the i'th partition value for the given
 * row.
 *
 * @param pVtab - the vec0_vtab in questions
 * @param rowid - rowid of target row
 * @param partition_idx - which partition column to retrieve
 * @param outValue - output sqlite3_value
 * @return int - SQLITE_OK on success, otherwise error code
 */
int vec0_get_partition_value_for_rowid(vec0_vtab *pVtab, i64 rowid,
                                       int partition_idx,
                                       sqlite3_value **outValue) {
  int rc;
  i64 chunk_id;
  i64 chunk_offset;
  rc = vec0_get_chunk_position(pVtab, rowid, NULL, &chunk_id, &chunk_offset);
  if (rc != SQLITE_OK) {
    return rc;
  }
  sqlite3_stmt *stmt = NULL;
  char *zSql =
      sqlite3_mprintf("SELECT partition%02d FROM " VEC0_SHADOW_CHUNKS_NAME
                      " WHERE chunk_id = ?",
                      partition_idx, pVtab->schemaName, pVtab->tableName);
  if (!zSql) {
    return SQLITE_NOMEM;
  }
  rc = sqlite3_prepare_v2(pVtab->db, zSql, -1, &stmt, NULL);
  sqlite3_free(zSql);
  if (rc != SQLITE_OK) {
    return rc;
  }
  sqlite3_bind_int64(stmt, 1, chunk_id);
  rc = sqlite3_step(stmt);
  if (rc != SQLITE_ROW) {
    rc = vec0_error_rc(rc);
    goto done;
  }
  *outValue = sqlite3_value_dup(sqlite3_column_value(stmt, 0));
  if (!*outValue) {
    rc = SQLITE_NOMEM;
    goto done;
  }
  rc = SQLITE_OK;

done:
  sqlite3_finalize(stmt);
  return rc;
}

/**
 * @brief Get the value of an auxiliary column for the given rowid
 *
 * @param pVtab vec0_vtab
 * @param rowid the rowid of the row to lookup
 * @param auxiliary_idx aux index of the column we care about
 * @param outValue Output sqlite3_value to store
 * @return int SQLITE_OK on success, error code otherwise
 */
int vec0_get_auxiliary_value_for_rowid(vec0_vtab *pVtab, i64 rowid,
                                       int auxiliary_idx,
                                       sqlite3_value **outValue) {
  int rc;
  sqlite3_stmt *stmt = NULL;
  char *zSql = sqlite3_mprintf(
      "SELECT value%02d FROM " VEC0_SHADOW_AUXILIARY_NAME " WHERE rowid = ?",
      auxiliary_idx, pVtab->schemaName, pVtab->tableName);
  if (!zSql) {
    return SQLITE_NOMEM;
  }
  rc = sqlite3_prepare_v2(pVtab->db, zSql, -1, &stmt, NULL);
  sqlite3_free(zSql);
  if (rc != SQLITE_OK) {
    return rc;
  }
  sqlite3_bind_int64(stmt, 1, rowid);
  rc = sqlite3_step(stmt);
  if (rc != SQLITE_ROW) {
    rc = vec0_error_rc(rc);
    goto done;
  }
  *outValue = sqlite3_value_dup(sqlite3_column_value(stmt, 0));
  if (!*outValue) {
    rc = SQLITE_NOMEM;
    goto done;
  }
  rc = SQLITE_OK;

done:
  sqlite3_finalize(stmt);
  return rc;
}

/**
 * @brief Result the given metadata value for the given row and metadata column
 * index. Will traverse the metadatachunksNN table with BLOB I/0 for the given
 * rowid.
 *
 * @param p
 * @param rowid
 * @param metadata_idx
 * @param context
 * @return int
 */
int vec0_result_metadata_value_for_rowid(vec0_vtab *p, i64 rowid,
                                         int metadata_idx,
                                         sqlite3_context *context) {
  int rc;
  i64 chunk_id;
  i64 chunk_offset;
  rc = vec0_get_chunk_position(p, rowid, NULL, &chunk_id, &chunk_offset);
  if (rc != SQLITE_OK) {
    return rc;
  }
  sqlite3_blob *blobValue;
  rc = sqlite3_blob_open(p->db, p->schemaName,
                         p->shadowMetadataChunksNames[metadata_idx], "data",
                         chunk_id, 0, &blobValue);
  if (rc != SQLITE_OK) {
    return rc;
  }

  switch (p->metadata_columns[metadata_idx].kind) {
  case VEC0_METADATA_COLUMN_KIND_BOOLEAN: {
    u8 block;
    rc = sqlite3_blob_read(blobValue, &block, sizeof(block),
                           chunk_offset / CHAR_BIT);
    if (rc != SQLITE_OK) {
      goto done;
    }
    int value = block >> ((chunk_offset % CHAR_BIT)) & 1;
    sqlite3_result_int(context, value);
    break;
  }
  case VEC0_METADATA_COLUMN_KIND_INTEGER: {
    i64 value;
    rc = sqlite3_blob_read(blobValue, &value, sizeof(value),
                           chunk_offset * sizeof(i64));
    if (rc != SQLITE_OK) {
      goto done;
    }
    sqlite3_result_int64(context, value);
    break;
  }
  case VEC0_METADATA_COLUMN_KIND_FLOAT: {
    double value;
    rc = sqlite3_blob_read(blobValue, &value, sizeof(value),
                           chunk_offset * sizeof(double));
    if (rc != SQLITE_OK) {
      goto done;
    }
    sqlite3_result_double(context, value);
    break;
  }
  case VEC0_METADATA_COLUMN_KIND_TEXT: {
    u8 view[VEC0_METADATA_TEXT_VIEW_BUFFER_LENGTH];
    rc = sqlite3_blob_read(
        blobValue, &view, VEC0_METADATA_TEXT_VIEW_BUFFER_LENGTH,
        chunk_offset * VEC0_METADATA_TEXT_VIEW_BUFFER_LENGTH);
    if (rc != SQLITE_OK) {
      goto done;
    }
    int length = ((int *)view)[0];
    if (length <= VEC0_METADATA_TEXT_VIEW_DATA_LENGTH) {
      sqlite3_result_text(context, (const char *)(view + 4), length,
                          SQLITE_TRANSIENT);
    } else {
      sqlite3_stmt *stmt;
      const char *zSql = sqlite3_mprintf(
          "SELECT data FROM " VEC0_SHADOW_METADATA_TEXT_DATA_NAME
          " WHERE rowid = ?",
          p->schemaName, p->tableName, metadata_idx);
      if (!zSql) {
        rc = SQLITE_ERROR;
        goto done;
      }
      rc = sqlite3_prepare_v2(p->db, zSql, -1, &stmt, NULL);
      sqlite3_free((void *)zSql);
      if (rc != SQLITE_OK) {
        goto done;
      }
      sqlite3_bind_int64(stmt, 1, rowid);
      rc = sqlite3_step(stmt);
      if (rc != SQLITE_ROW) {
        sqlite3_finalize(stmt);
        rc = vec0_error_rc(rc);
        goto done;
      }
      sqlite3_result_value(context, sqlite3_column_value(stmt, 0));
      sqlite3_finalize(stmt);
      rc = SQLITE_OK;
    }
    break;
  }
  }
done:
  // blobValue is read-only, will not fail on close
  sqlite3_blob_close(blobValue);
  return rc;
}

int vec0_get_latest_chunk_rowid(vec0_vtab *p, i64 *chunk_rowid,
                                sqlite3_value **partitionKeyValues) {
  int rc;
  const char *zSql;
  // lazy initialize stmtLatestChunk when needed. May be cleared during xSync()
  if (!p->stmtLatestChunk) {
    if (p->numPartitionColumns > 0) {
      sqlite3_str *s = sqlite3_str_new(NULL);
      sqlite3_str_appendf(
          s, "SELECT max(rowid) FROM " VEC0_SHADOW_CHUNKS_NAME " WHERE ",
          p->schemaName, p->tableName);

      for (int i = 0; i < p->numPartitionColumns; i++) {
        if (i != 0) {
          sqlite3_str_appendall(s, " AND ");
        }
        sqlite3_str_appendf(s, " partition%02d = ? ", i);
      }
      zSql = sqlite3_str_finish(s);
    } else {
      zSql = sqlite3_mprintf("SELECT max(rowid) FROM " VEC0_SHADOW_CHUNKS_NAME,
                             p->schemaName, p->tableName);
    }

    if (!zSql) {
      rc = SQLITE_NOMEM;
      goto cleanup;
    }
    rc = sqlite3_prepare_v2(p->db, zSql, -1, &p->stmtLatestChunk, 0);
    sqlite3_free((void *)zSql);
    if (rc != SQLITE_OK) {
      // IMP: V21406_05476
      vtab_set_error(&p->base, VEC_INTERAL_ERROR
                     "could not initialize 'latest chunk' statement");
      goto cleanup;
    }
  }

  for (int i = 0; i < p->numPartitionColumns; i++) {
    sqlite3_bind_value(p->stmtLatestChunk, i + 1, (partitionKeyValues[i]));
  }

  rc = sqlite3_step(p->stmtLatestChunk);
  if (rc != SQLITE_ROW) {
    // IMP: V31559_15629
    vtab_set_error(&p->base, VEC_INTERAL_ERROR "Could not find latest chunk");
    rc = vec0_error_rc(rc);
    goto cleanup;
  }
  if (sqlite3_column_type(p->stmtLatestChunk, 0) == SQLITE_NULL) {
    rc = SQLITE_EMPTY;
    goto cleanup;
  }
  *chunk_rowid = sqlite3_column_int64(p->stmtLatestChunk, 0);
  rc = sqlite3_step(p->stmtLatestChunk);
  if (rc != SQLITE_DONE) {
    vtab_set_error(&p->base,
                   VEC_INTERAL_ERROR
                   "unknown result code when closing out stmtLatestChunk. "
                   "Please file an issue: " REPORT_URL,
                   p->schemaName, p->shadowChunksName);
    goto cleanup;
  }
  rc = SQLITE_OK;

cleanup:
  if (p->stmtLatestChunk) {
    sqlite3_reset(p->stmtLatestChunk);
    sqlite3_clear_bindings(p->stmtLatestChunk);
  }
  return rc;
}

int vec0_rowids_insert_rowid(vec0_vtab *p, i64 rowid) {
  int rc = SQLITE_OK;
  int entered = 0;
  UNUSED_PARAMETER(entered); // temporary
  if (!p->stmtRowidsInsertRowid) {
    const char *zSql =
        sqlite3_mprintf("INSERT INTO " VEC0_SHADOW_ROWIDS_NAME "(rowid)"
                        "VALUES (?);",
                        p->schemaName, p->tableName);
    if (!zSql) {
      rc = SQLITE_NOMEM;
      goto cleanup;
    }
    rc = sqlite3_prepare_v2(p->db, zSql, -1, &p->stmtRowidsInsertRowid, 0);
    sqlite3_free((void *)zSql);
    if (rc != SQLITE_OK) {
      vtab_set_error(&p->base, VEC_INTERAL_ERROR
                     "could not initialize 'insert rowids' statement");
      goto cleanup;
    }
  }

#if SQLITE_THREADSAFE
  if (sqlite3_mutex_enter) {
    sqlite3_mutex_enter(sqlite3_db_mutex(p->db));
    entered = 1;
  }
#endif
  sqlite3_bind_int64(p->stmtRowidsInsertRowid, 1, rowid);
  rc = sqlite3_step(p->stmtRowidsInsertRowid);

  if (rc != SQLITE_DONE) {
    if (sqlite3_extended_errcode(p->db) == SQLITE_CONSTRAINT_PRIMARYKEY) {
      // IMP: V17090_01160
      vtab_set_error(&p->base, "UNIQUE constraint failed on %s primary key",
                     p->tableName);
    } else {
      // IMP: V04679_21517
      vtab_set_error(&p->base,
                     "Error inserting rowid into rowids shadow table: %s",
                     sqlite3_errmsg(p->db));
    }
    rc = vec0_error_rc(rc);
    goto cleanup;
  }

  rc = SQLITE_OK;

cleanup:
  if (p->stmtRowidsInsertRowid) {
    sqlite3_reset(p->stmtRowidsInsertRowid);
    sqlite3_clear_bindings(p->stmtRowidsInsertRowid);
  }

#if SQLITE_THREADSAFE
  if (sqlite3_mutex_leave && entered) {
    sqlite3_mutex_leave(sqlite3_db_mutex(p->db));
  }
#endif
  return rc;
}

int vec0_rowids_insert_id(vec0_vtab *p, sqlite3_value *idValue, i64 *rowid) {
  int rc = SQLITE_OK;
  int entered = 0;
  UNUSED_PARAMETER(entered); // temporary
  if (!p->stmtRowidsInsertId) {
    const char *zSql =
        sqlite3_mprintf("INSERT INTO " VEC0_SHADOW_ROWIDS_NAME "(id)"
                        "VALUES (?);",
                        p->schemaName, p->tableName);
    if (!zSql) {
      rc = SQLITE_NOMEM;
      goto complete;
    }
    rc = sqlite3_prepare_v2(p->db, zSql, -1, &p->stmtRowidsInsertId, 0);
    sqlite3_free((void *)zSql);
    if (rc != SQLITE_OK) {
      vtab_set_error(&p->base, VEC_INTERAL_ERROR
                     "could not initialize 'insert rowids id' statement");
      goto complete;
    }
  }

#if SQLITE_THREADSAFE
  if (sqlite3_mutex_enter) {
    sqlite3_mutex_enter(sqlite3_db_mutex(p->db));
    entered = 1;
  }
#endif

  if (idValue) {
    sqlite3_bind_value(p->stmtRowidsInsertId, 1, idValue);
  }
  rc = sqlite3_step(p->stmtRowidsInsertId);

  if (rc != SQLITE_DONE) {
    if (sqlite3_extended_errcode(p->db) == SQLITE_CONSTRAINT_UNIQUE) {
      // IMP: V20497_04568
      vtab_set_error(&p->base, "UNIQUE constraint failed on %s primary key",
                     p->tableName);
    } else {
      // IMP: V24016_08086
      // IMP: V15177_32015
      vtab_set_error(&p->base,
                     "Error inserting id into rowids shadow table: %s",
                     sqlite3_errmsg(p->db));
    }
    rc = vec0_error_rc(rc);
    goto complete;
  }

  *rowid = sqlite3_last_insert_rowid(p->db);
  rc = SQLITE_OK;

complete:
  if (p->stmtRowidsInsertId) {
    sqlite3_reset(p->stmtRowidsInsertId);
    sqlite3_clear_bindings(p->stmtRowidsInsertId);
  }

#if SQLITE_THREADSAFE
  if (sqlite3_mutex_leave && entered) {
    sqlite3_mutex_leave(sqlite3_db_mutex(p->db));
  }
#endif
  return rc;
}

int vec0_metadata_chunk_size(vec0_metadata_column_kind kind, int chunk_size) {
  switch (kind) {
  case VEC0_METADATA_COLUMN_KIND_BOOLEAN:
    return chunk_size / 8;
  case VEC0_METADATA_COLUMN_KIND_INTEGER:
    return chunk_size * sizeof(i64);
  case VEC0_METADATA_COLUMN_KIND_FLOAT:
    return chunk_size * sizeof(double);
  case VEC0_METADATA_COLUMN_KIND_TEXT:
    return chunk_size * VEC0_METADATA_TEXT_VIEW_BUFFER_LENGTH;
  }
  return 0;
}

int vec0_rowids_update_position(vec0_vtab *p, i64 rowid, i64 chunk_rowid,
                                i64 chunk_offset) {
  int rc = SQLITE_OK;

  if (!p->stmtRowidsUpdatePosition) {
    const char *zSql = sqlite3_mprintf(" UPDATE " VEC0_SHADOW_ROWIDS_NAME
                                       " SET chunk_id = ?, chunk_offset = ?"
                                       " WHERE rowid = ?",
                                       p->schemaName, p->tableName);
    if (!zSql) {
      rc = SQLITE_NOMEM;
      goto cleanup;
    }
    rc = sqlite3_prepare_v2(p->db, zSql, -1, &p->stmtRowidsUpdatePosition, 0);
    sqlite3_free((void *)zSql);
    if (rc != SQLITE_OK) {
      vtab_set_error(&p->base, VEC_INTERAL_ERROR
                     "could not initialize 'update rowids position' statement");
      goto cleanup;
    }
  }

  sqlite3_bind_int64(p->stmtRowidsUpdatePosition, 1, chunk_rowid);
  sqlite3_bind_int64(p->stmtRowidsUpdatePosition, 2, chunk_offset);
  sqlite3_bind_int64(p->stmtRowidsUpdatePosition, 3, rowid);

  rc = sqlite3_step(p->stmtRowidsUpdatePosition);
  if (rc != SQLITE_DONE) {
    // IMP: V21925_05995
    vtab_set_error(&p->base,
                   VEC_INTERAL_ERROR
                   "could not update rowids position for rowid=%lld, "
                   "chunk_rowid=%lld, chunk_offset=%lld",
                   rowid, chunk_rowid, chunk_offset);
    rc = vec0_error_rc(rc);
    goto cleanup;
  }
  rc = SQLITE_OK;

cleanup:
  if (p->stmtRowidsUpdatePosition) {
    sqlite3_reset(p->stmtRowidsUpdatePosition);
    sqlite3_clear_bindings(p->stmtRowidsUpdatePosition);
  }

  return rc;
}

/**
 * @brief Adds a new chunk for the vec0 table, and the corresponding vector
 * chunks.
 *
 * Inserts a new row into the _chunks table, with blank data, and uses that new
 * rowid to insert new blank rows into _vector_chunksXX tables.
 *
 * @param p: vec0 table to add new chunk
 * @param paritionKeyValues: Array of partition key valeus for the new chunk, if
 * available
 * @param chunk_rowid: Output pointer, if not NULL, then will be filled with the
 * new chunk rowid.
 * @return int SQLITE_OK on success, error code otherwise.
 */
int vec0_new_chunk(vec0_vtab *p, sqlite3_value **partitionKeyValues,
                   i64 *chunk_rowid) {
  int rc;
  char *zSql;
  sqlite3_stmt *stmt;
  i64 rowid;

  // Step 1: Insert a new row in _chunks, capture that new rowid
  if (p->numPartitionColumns > 0) {
    sqlite3_str *s = sqlite3_str_new(NULL);
    sqlite3_str_appendf(s, "INSERT INTO " VEC0_SHADOW_CHUNKS_NAME,
                        p->schemaName, p->tableName);
    sqlite3_str_appendall(s, "(size, validity, rowids");
    for (int i = 0; i < p->numPartitionColumns; i++) {
      sqlite3_str_appendf(s, ", partition%02d", i);
    }
    sqlite3_str_appendall(s, ") VALUES (?, ?, ?");
    for (int i = 0; i < p->numPartitionColumns; i++) {
      sqlite3_str_appendall(s, ", ?");
    }
    sqlite3_str_appendall(s, ")");

    zSql = sqlite3_str_finish(s);
  } else {
    zSql = sqlite3_mprintf("INSERT INTO " VEC0_SHADOW_CHUNKS_NAME
                           "(size, validity, rowids) "
                           "VALUES (?, ?, ?);",
                           p->schemaName, p->tableName);
  }

  if (!zSql) {
    return SQLITE_NOMEM;
  }
  rc = sqlite3_prepare_v2(p->db, zSql, -1, &stmt, NULL);
  sqlite3_free(zSql);
  if (rc != SQLITE_OK) {
    sqlite3_finalize(stmt);
    return rc;
  }

#if SQLITE_THREADSAFE
  if (sqlite3_mutex_enter) {
    sqlite3_mutex_enter(sqlite3_db_mutex(p->db));
  }
#endif

  sqlite3_bind_int64(stmt, 1, p->chunk_size);               // size
  sqlite3_bind_zeroblob(stmt, 2, p->chunk_size / CHAR_BIT); // validity bitmap
  sqlite3_bind_zeroblob(stmt, 3, p->chunk_size * sizeof(i64)); // rowids

  for (int i = 0; i < p->numPartitionColumns; i++) {
    sqlite3_bind_value(stmt, 4 + i, partitionKeyValues[i]);
  }

  rc = sqlite3_step(stmt);
  rowid = sqlite3_last_insert_rowid(p->db);
#if SQLITE_THREADSAFE
  if (sqlite3_mutex_leave) {
    sqlite3_mutex_leave(sqlite3_db_mutex(p->db));
  }
#endif
  sqlite3_finalize(stmt);
  if (rc != SQLITE_DONE) {
    return vec0_error_rc(rc);
  }

  // Step 2: Create new vector chunks for each vector column, with
  //          that new chunk_rowid.

  for (int i = 0; i < vec0_num_defined_user_columns(p); i++) {
    if (p->user_column_kinds[i] != SQLITE_VEC0_USER_COLUMN_KIND_VECTOR) {
      continue;
    }
    int vector_column_idx = p->user_column_idxs[i];
    i64 vectorsSize = p->chunk_size * vector_column_byte_size(
                                          p->vector_columns[vector_column_idx]);

    // SHADOW_TABLE_ROWID_QUIRK: tables created before v0.2.0-alpha declare
    // _vector_chunksNN and _metadatachunksNN with "rowid PRIMARY KEY", without
    // INTEGER, so their "rowid" column is not an alias for SQLite's _rowid_.
    // sqlite3_blob_open() addresses rows by _rowid_, and once a chunk is
    // deleted, an auto-assigned _rowid_ can differ from the chunk_id stored in
    // "rowid", so set both. In newer tables both names are the same column.
    zSql = sqlite3_mprintf("INSERT INTO " VEC0_SHADOW_VECTOR_N_NAME
                           "(_rowid_, rowid, vectors)"
                           "VALUES (?, ?, ?)",
                           p->schemaName, p->tableName, vector_column_idx);
    if (!zSql) {
      return SQLITE_NOMEM;
    }
    rc = sqlite3_prepare_v2(p->db, zSql, -1, &stmt, NULL);
    sqlite3_free(zSql);

    if (rc != SQLITE_OK) {
      sqlite3_finalize(stmt);
      return rc;
    }

    sqlite3_bind_int64(stmt, 1, rowid);
    sqlite3_bind_int64(stmt, 2, rowid);
    sqlite3_bind_zeroblob64(stmt, 3, vectorsSize);

    rc = sqlite3_step(stmt);
    sqlite3_finalize(stmt);
    if (rc != SQLITE_DONE) {
      return rc;
    }
  }

  // Step 3: Create new metadata chunks for each metadata column
  for (int i = 0; i < vec0_num_defined_user_columns(p); i++) {
    if (p->user_column_kinds[i] != SQLITE_VEC0_USER_COLUMN_KIND_METADATA) {
      continue;
    }
    int metadata_column_idx = p->user_column_idxs[i];
    // see SHADOW_TABLE_ROWID_QUIRK above for why _rowid_ and rowid are both set
    zSql = sqlite3_mprintf("INSERT INTO " VEC0_SHADOW_METADATA_N_NAME
                           "(_rowid_, rowid, data)"
                           "VALUES (?, ?, ?)",
                           p->schemaName, p->tableName, metadata_column_idx);
    if (!zSql) {
      return SQLITE_NOMEM;
    }
    rc = sqlite3_prepare_v2(p->db, zSql, -1, &stmt, NULL);
    sqlite3_free(zSql);

    if (rc != SQLITE_OK) {
      sqlite3_finalize(stmt);
      return rc;
    }

    sqlite3_bind_int64(stmt, 1, rowid);
    sqlite3_bind_int64(stmt, 2, rowid);
    sqlite3_bind_zeroblob64(
        stmt, 3,
        vec0_metadata_chunk_size(p->metadata_columns[metadata_column_idx].kind,
                                 p->chunk_size));

    rc = sqlite3_step(stmt);
    sqlite3_finalize(stmt);
    if (rc != SQLITE_DONE) {
      return rc;
    }
  }

  if (chunk_rowid) {
    *chunk_rowid = rowid;
  }

  return SQLITE_OK;
}

struct vec0_query_fullscan_data {
  // Every rowid, in storage order as of the scan's start.
  sqlite3_stmt *rowids_stmt;
  i8 done;
  // Per vector column, a handle on the vectors blob of the chunk the scan last
  // read from. A chunk's blob holds chunk_size vectors, and the first read
  // through a newly opened handle walks the blob's overflow pages up to the
  // row's offset, so a scan keeps it open across the chunk's rows instead of
  // opening it once per row.
  sqlite3_blob *vectorBlobs[VEC0_MAX_VECTOR_COLUMNS];
  i64 vectorBlobChunkIds[VEC0_MAX_VECTOR_COLUMNS];
};
void vec0_query_fullscan_data_clear(
    struct vec0_query_fullscan_data *fullscan_data) {
  if (!fullscan_data)
    return;

  if (fullscan_data->rowids_stmt) {
    sqlite3_finalize(fullscan_data->rowids_stmt);
    fullscan_data->rowids_stmt = NULL;
  }
  for (int i = 0; i < VEC0_MAX_VECTOR_COLUMNS; i++) {
    sqlite3_blob_close(fullscan_data->vectorBlobs[i]);
    fullscan_data->vectorBlobs[i] = NULL;
  }
}

struct vec0_query_knn_data {
  i64 k;
  i64 k_used;
  // Array of rowids of size k. Must be freed with sqlite3_free().
  i64 *rowids;
  // Array of distances of size k. Must be freed with sqlite3_free().
  f32 *distances;
  i64 current_idx;
};
void vec0_query_knn_data_clear(struct vec0_query_knn_data *knn_data) {
  if (!knn_data)
    return;

  if (knn_data->rowids) {
    sqlite3_free(knn_data->rowids);
    knn_data->rowids = NULL;
  }
  if (knn_data->distances) {
    sqlite3_free(knn_data->distances);
    knn_data->distances = NULL;
  }
}

struct vec0_query_point_data {
  i64 rowid;
  void *vectors[VEC0_MAX_VECTOR_COLUMNS];
  int done;
};
void vec0_query_point_data_clear(struct vec0_query_point_data *point_data) {
  if (!point_data)
    return;
  for (int i = 0; i < VEC0_MAX_VECTOR_COLUMNS; i++) {
    sqlite3_free(point_data->vectors[i]);
    point_data->vectors[i] = NULL;
  }
}

typedef enum {
  // If any values are updated, please update the ARCHITECTURE.md docs
  // accordingly!

  VEC0_QUERY_PLAN_FULLSCAN = '1',
  VEC0_QUERY_PLAN_POINT = '2',
  VEC0_QUERY_PLAN_KNN = '3',
} vec0_query_plan;

typedef struct vec0_cursor vec0_cursor;
struct vec0_cursor {
  sqlite3_vtab_cursor base;

  vec0_query_plan query_plan;
  struct vec0_query_fullscan_data *fullscan_data;
  struct vec0_query_knn_data *knn_data;
  struct vec0_query_point_data *point_data;
};

void vec0_cursor_clear(vec0_cursor *pCur) {
  if (pCur->fullscan_data) {
    vec0_query_fullscan_data_clear(pCur->fullscan_data);
    sqlite3_free(pCur->fullscan_data);
    pCur->fullscan_data = NULL;
  }
  if (pCur->knn_data) {
    vec0_query_knn_data_clear(pCur->knn_data);
    sqlite3_free(pCur->knn_data);
    pCur->knn_data = NULL;
  }
  if (pCur->point_data) {
    vec0_query_point_data_clear(pCur->point_data);
    sqlite3_free(pCur->point_data);
    pCur->point_data = NULL;
  }
}

// Reads the database's text encoding into *pEncoding: SQLITE_UTF8,
// SQLITE_UTF16LE or SQLITE_UTF16BE. Every attached database shares the main
// database's encoding. SQLite converts a string literal to the database's
// encoding when it runs the statement, so on SQLite 3.41+
// sqlite3_value_encoding() of one reports it without a PRAGMA, which an
// application's authorizer may deny. Older SQLite reads PRAGMA encoding, which
// names it "UTF-8", "UTF-16le" or "UTF-16be". A build with SQLITE_OMIT_UTF16
// has no such pragma, so it returns no row there, where every database is UTF-8
// (PragTyp_ENCODING in https://sqlite.org/src/file/src/pragma.c and
// sqlite3InitOne() in https://sqlite.org/src/file/src/prepare.c); an authorizer
// that ignores the pragma also returns no row, so in any other build that is
// SQLITE_EMPTY.
static int vec0_read_text_encoding(sqlite3 *db, int *pEncoding) {
  sqlite3_stmt *stmt = NULL;
  int rc;
#if COMPILER_SUPPORTS_VALUE_ENCODING
  if (sqlite3_libversion_number() >= 3041000) {
    rc = sqlite3_prepare_v2(db, "SELECT 'a'", -1, &stmt, NULL);
    if (rc == SQLITE_OK) {
      rc = sqlite3_step(stmt);
      if (rc == SQLITE_ROW) {
        *pEncoding = sqlite3_value_encoding(sqlite3_column_value(stmt, 0));
        rc = SQLITE_OK;
      }
    }
    sqlite3_finalize(stmt);
    return rc;
  }
#endif
  rc = sqlite3_prepare_v2(db, "PRAGMA encoding", -1, &stmt, NULL);
  if (rc != SQLITE_OK) {
    return rc;
  }
  *pEncoding = SQLITE_UTF8;
  rc = sqlite3_step(stmt);
  if (rc == SQLITE_ROW) {
    const char *zEncoding = (const char *)sqlite3_column_text(stmt, 0);
    if (!zEncoding) {
      rc = SQLITE_NOMEM;
    } else {
      if (sqlite3_stricmp(zEncoding, "UTF-16le") == 0) {
        *pEncoding = SQLITE_UTF16LE;
      } else if (sqlite3_stricmp(zEncoding, "UTF-16be") == 0) {
        *pEncoding = SQLITE_UTF16BE;
      }
      rc = SQLITE_OK;
    }
  } else if (rc == SQLITE_DONE) {
    // A host built with SQLITE_OMIT_COMPILEOPTION_DIAGS gives an extension no
    // sqlite3_compileoption_used(), so it cannot confirm SQLITE_OMIT_UTF16
#ifndef SQLITE_CORE
    int canAsk = sqlite3_api->compileoption_used != NULL;
#else
    int canAsk = 1;
#endif
    rc = canAsk && sqlite3_compileoption_used("OMIT_UTF16") ? SQLITE_OK
                                                            : SQLITE_EMPTY;
  }
  sqlite3_finalize(stmt);
  return rc;
}

#define VEC_CONSTRUCTOR_ERROR "vec0 constructor error: "
static int vec0_init(sqlite3 *db, void *pAux, int argc, const char *const *argv,
                     sqlite3_vtab **ppVtab, char **pzErr, bool isCreate) {
  UNUSED_PARAMETER(pAux);
  vec0_vtab *pNew;
  int rc;
  const char *zSql;

  // The text filters need the encoding, so a failed read fails the
  // constructor; an interrupted one reports as an interrupt, as
  // vec0_interrupt_result() makes the other methods do.
  int textEncoding;
  rc = vec0_read_text_encoding(db, &textEncoding);
  if (rc != SQLITE_OK) {
    if (rc == SQLITE_INTERRUPT) {
      *pzErr = sqlite3_mprintf("%s", sqlite3_errstr(rc));
    } else {
      *pzErr =
          sqlite3_mprintf(VEC_CONSTRUCTOR_ERROR
                          "could not read the database's text encoding: %s",
                          rc == SQLITE_EMPTY ? "PRAGMA encoding returned no row"
                                             : sqlite3_errmsg(db));
    }
    return vec0_error_rc(rc);
  }

  pNew = sqlite3_malloc(sizeof(*pNew));
  if (pNew == 0)
    return SQLITE_NOMEM;
  memset(pNew, 0, sizeof(*pNew));

  // Declared chunk_size=N for entire table.
  // -1 to use the defualt, otherwise will get re-assigned on `chunk_size=N`
  // option
  int chunk_size = -1;
  int numVectorColumns = 0;
  int numPartitionColumns = 0;
  int numAuxiliaryColumns = 0;
  int numMetadataColumns = 0;
  int user_column_idx = 0;

  // track if a "primary key" column is defined
  char *pkColumnName = NULL;
  int pkColumnNameLength;
  int pkColumnType = SQLITE_INTEGER;

  for (int i = 3; i < argc; i++) {
    struct VectorColumnDefinition vecColumn;
    struct Vec0PartitionColumnDefinition partitionColumn;
    struct Vec0AuxiliaryColumnDefinition auxColumn;
    struct Vec0MetadataColumnDefinition metadataColumn;
    char *cName = NULL;
    int cNameLength;
    int cType;

    // Scenario #1: Constructor argument is a vector column definition, ie `foo
    // float[1024]`
    rc = vec0_parse_vector_column(argv[i], strlen(argv[i]), &vecColumn, true);
    // vec0 re-parses the stored CREATE text on every connect, and 2.0.2 and
    // earlier created tables whose vector definitions only the non-strict
    // parse reads, such as `5 float[4]`. Connect uses that reading only when
    // the strict parse fails, so `+bits text`, an auxiliary column that 2.0.2
    // misread as a vector column and rejected, stays an auxiliary column.
    if (rc != SQLITE_OK && !isCreate &&
        vec0_parse_vector_column(argv[i], strlen(argv[i]), &vecColumn, false) ==
            SQLITE_OK) {
      rc = SQLITE_OK;
    }
    if (rc == SQLITE_ERROR) {
      *pzErr = sqlite3_mprintf(
          VEC_CONSTRUCTOR_ERROR "could not parse vector column '%s'", argv[i]);
      goto error;
    }
    if (rc == SQLITE_OK) {
      if (numVectorColumns >= VEC0_MAX_VECTOR_COLUMNS) {
        sqlite3_free(vecColumn.name);
        *pzErr = sqlite3_mprintf(VEC_CONSTRUCTOR_ERROR
                                 "Too many provided vector columns, maximum %d",
                                 VEC0_MAX_VECTOR_COLUMNS);
        goto error;
      }

      if (vecColumn.dimensions > SQLITE_VEC_VEC0_MAX_DIMENSIONS) {
        sqlite3_free(vecColumn.name);
        *pzErr = sqlite3_mprintf(
            VEC_CONSTRUCTOR_ERROR
            "Dimension on vector column too large, provided %lld, maximum %lld",
            (i64)vecColumn.dimensions, SQLITE_VEC_VEC0_MAX_DIMENSIONS);
        goto error;
      }
      pNew->user_column_kinds[user_column_idx] =
          SQLITE_VEC0_USER_COLUMN_KIND_VECTOR;
      pNew->user_column_idxs[user_column_idx] = numVectorColumns;
      memcpy(&pNew->vector_columns[numVectorColumns], &vecColumn,
             sizeof(vecColumn));
      numVectorColumns++;
      user_column_idx++;

      continue;
    }

    // Scenario #2: Constructor argument is a partition key column definition,
    // ie `user_id text partition key`
    rc = vec0_parse_partition_key_definition(argv[i], strlen(argv[i]), &cName,
                                             &cNameLength, &cType, isCreate);
    if (rc == SQLITE_OK) {
      if (numPartitionColumns >= VEC0_MAX_PARTITION_COLUMNS) {
        *pzErr =
            sqlite3_mprintf(VEC_CONSTRUCTOR_ERROR
                            "More than %d partition key columns were provided",
                            VEC0_MAX_PARTITION_COLUMNS);
        goto error;
      }
      partitionColumn.type = cType;
      partitionColumn.name_length = cNameLength;
      partitionColumn.name = sqlite3_mprintf("%.*s", cNameLength, cName);
      if (!partitionColumn.name) {
        rc = SQLITE_NOMEM;
        goto error;
      }

      pNew->user_column_kinds[user_column_idx] =
          SQLITE_VEC0_USER_COLUMN_KIND_PARTITION;
      pNew->user_column_idxs[user_column_idx] = numPartitionColumns;
      memcpy(&pNew->paritition_columns[numPartitionColumns], &partitionColumn,
             sizeof(partitionColumn));
      numPartitionColumns++;
      user_column_idx++;
      continue;
    }

    // Scenario #3: Constructor argument is a primary key column definition, ie
    // `article_id text primary key`
    rc = vec0_parse_primary_key_definition(argv[i], strlen(argv[i]), &cName,
                                           &cNameLength, &cType, isCreate);
    if (rc == SQLITE_OK) {
      if (pkColumnName) {
        *pzErr = sqlite3_mprintf(
            VEC_CONSTRUCTOR_ERROR
            "More than one primary key definition was provided, vec0 only "
            "supports a single primary key column");
        goto error;
      }
      pkColumnName = cName;
      pkColumnNameLength = cNameLength;
      pkColumnType = cType;
      continue;
    }

    // Scenario #4: Constructor argument is a auxiliary column definition, ie
    // `+contents text`
    rc = vec0_parse_auxiliary_column_definition(
        argv[i], strlen(argv[i]), &cName, &cNameLength, &cType, isCreate);
    if (rc == SQLITE_OK) {
      if (numAuxiliaryColumns >= VEC0_MAX_AUXILIARY_COLUMNS) {
        *pzErr = sqlite3_mprintf(VEC_CONSTRUCTOR_ERROR
                                 "More than %d auxiliary columns were provided",
                                 VEC0_MAX_AUXILIARY_COLUMNS);
        goto error;
      }
      auxColumn.type = cType;
      auxColumn.name_length = cNameLength;
      auxColumn.name = sqlite3_mprintf("%.*s", cNameLength, cName);
      if (!auxColumn.name) {
        rc = SQLITE_NOMEM;
        goto error;
      }

      pNew->user_column_kinds[user_column_idx] =
          SQLITE_VEC0_USER_COLUMN_KIND_AUXILIARY;
      pNew->user_column_idxs[user_column_idx] = numAuxiliaryColumns;
      memcpy(&pNew->auxiliary_columns[numAuxiliaryColumns], &auxColumn,
             sizeof(auxColumn));
      numAuxiliaryColumns++;
      user_column_idx++;
      continue;
    }

    vec0_metadata_column_kind kind;
    rc = vec0_parse_metadata_column_definition(argv[i], strlen(argv[i]), &cName,
                                               &cNameLength, &kind, isCreate);
    if (rc == SQLITE_OK) {
      if (numMetadataColumns >= VEC0_MAX_METADATA_COLUMNS) {
        *pzErr = sqlite3_mprintf(VEC_CONSTRUCTOR_ERROR
                                 "More than %d metadata columns were provided",
                                 VEC0_MAX_METADATA_COLUMNS);
        goto error;
      }
      metadataColumn.kind = kind;
      metadataColumn.name_length = cNameLength;
      metadataColumn.name = sqlite3_mprintf("%.*s", cNameLength, cName);
      if (!metadataColumn.name) {
        rc = SQLITE_NOMEM;
        goto error;
      }

      pNew->user_column_kinds[user_column_idx] =
          SQLITE_VEC0_USER_COLUMN_KIND_METADATA;
      pNew->user_column_idxs[user_column_idx] = numMetadataColumns;
      memcpy(&pNew->metadata_columns[numMetadataColumns], &metadataColumn,
             sizeof(metadataColumn));
      numMetadataColumns++;
      user_column_idx++;
      continue;
    }

    // Scenario #4: Constructor argument is a table-level option, ie
    // `chunk_size`

    char *key;
    char *value;
    int keyLength, valueLength;
    rc = vec0_parse_table_option(argv[i], strlen(argv[i]), &key, &keyLength,
                                 &value, &valueLength);
    if (rc == SQLITE_ERROR) {
      *pzErr = sqlite3_mprintf(
          VEC_CONSTRUCTOR_ERROR "could not parse table option '%s'", argv[i]);
      goto error;
    }
    if (rc == SQLITE_OK) {
      if (sqlite3_strnicmp(key, "chunk_size", keyLength) == 0) {
        errno = 0;
        char *endptr;
        long parsed_chunk_size = strtol(value, &endptr, 10);
        if (errno == ERANGE || endptr != value + valueLength ||
            parsed_chunk_size <= 0 || parsed_chunk_size > INT_MAX) {
          // IMP: V01931_18769
          *pzErr =
              sqlite3_mprintf(VEC_CONSTRUCTOR_ERROR
                              "chunk_size must be a non-zero positive integer");
          goto error;
        }
        chunk_size = (int)parsed_chunk_size;
        if ((chunk_size % 8) != 0) {
          // IMP: V14110_30948
          *pzErr = sqlite3_mprintf(VEC_CONSTRUCTOR_ERROR
                                   "chunk_size must be divisible by 8");
          goto error;
        }
#define SQLITE_VEC_CHUNK_SIZE_MAX 4096
        if (chunk_size > SQLITE_VEC_CHUNK_SIZE_MAX) {
          *pzErr =
              sqlite3_mprintf(VEC_CONSTRUCTOR_ERROR "chunk_size too large");
          goto error;
        }
      } else {
        // IMP: V27642_11712
        *pzErr = sqlite3_mprintf(
            VEC_CONSTRUCTOR_ERROR "Unknown table option: %.*s", keyLength, key);
        goto error;
      }
      continue;
    }

    // Scenario #5: Unknown constructor argument
    *pzErr =
        sqlite3_mprintf(VEC_CONSTRUCTOR_ERROR "Could not parse '%s'", argv[i]);
    goto error;
  }

  if (chunk_size < 0) {
    chunk_size = 1024;
  }

  if (numVectorColumns <= 0) {
    *pzErr = sqlite3_mprintf(VEC_CONSTRUCTOR_ERROR
                             "At least one vector column is required");
    goto error;
  }

  const char *schemaName = argv[1];
  const char *tableName = argv[2];

  // The hidden command column has the table's name, so a table with another
  // column of that name gets none: the duplicate would fail to declare. CREATE
  // rejects such tables; older releases allowed them, and ALTER TABLE RENAME
  // can still make one.
  int tableNameLength = (int)strlen(tableName);
  int hasCommandColumn = 1;

  sqlite3_str *createStr = sqlite3_str_new(NULL);
  sqlite3_str_appendall(createStr, "CREATE TABLE x(");
  // vec0 stores only integer rowids, and an integer primary key is stored as
  // the rowid. Declaring that column INTEGER makes SQLite compare a value with
  // it as it does with an ordinary table's rowid, so `rowid > '3'` reads '3' as
  // the number 3.
  if (pkColumnName) {
    sqlite3_str_appendf(createStr, "\"%.*w\" %sprimary key, ",
                        pkColumnNameLength, pkColumnName,
                        pkColumnType == SQLITE_INTEGER ? "integer " : "");
    if (pkColumnNameLength == tableNameLength &&
        sqlite3_strnicmp(pkColumnName, tableName, tableNameLength) == 0) {
      hasCommandColumn = 0;
    }
  } else {
    sqlite3_str_appendall(createStr, "rowid integer, ");
    if (sqlite3_stricmp(tableName, "rowid") == 0) {
      hasCommandColumn = 0;
    }
  }
  for (int i = 0; i < numVectorColumns + numPartitionColumns +
                          numAuxiliaryColumns + numMetadataColumns;
       i++) {
    const char *name = NULL;
    int name_length = 0;
    switch (pNew->user_column_kinds[i]) {
    case SQLITE_VEC0_USER_COLUMN_KIND_VECTOR: {
      int vector_idx = pNew->user_column_idxs[i];
      name = pNew->vector_columns[vector_idx].name;
      name_length = pNew->vector_columns[vector_idx].name_length;
      break;
    }
    case SQLITE_VEC0_USER_COLUMN_KIND_PARTITION: {
      int partition_idx = pNew->user_column_idxs[i];
      name = pNew->paritition_columns[partition_idx].name;
      name_length = pNew->paritition_columns[partition_idx].name_length;
      break;
    }
    case SQLITE_VEC0_USER_COLUMN_KIND_AUXILIARY: {
      int auxiliary_idx = pNew->user_column_idxs[i];
      name = pNew->auxiliary_columns[auxiliary_idx].name;
      name_length = pNew->auxiliary_columns[auxiliary_idx].name_length;
      break;
    }
    case SQLITE_VEC0_USER_COLUMN_KIND_METADATA: {
      int metadata_idx = pNew->user_column_idxs[i];
      name = pNew->metadata_columns[metadata_idx].name;
      name_length = pNew->metadata_columns[metadata_idx].name_length;
      break;
    }
    }
    sqlite3_str_appendf(createStr, "\"%.*w\", ", name_length, name);
    if (name_length == tableNameLength &&
        sqlite3_strnicmp(name, tableName, tableNameLength) == 0) {
      hasCommandColumn = 0;
    }
  }
  if (sqlite3_stricmp(tableName, "distance") == 0 ||
      sqlite3_stricmp(tableName, "k") == 0 ||
      sqlite3_stricmp(tableName, "mmr_lambda") == 0) {
    hasCommandColumn = 0;
  }
  if (isCreate && !hasCommandColumn) {
    sqlite3_free(sqlite3_str_finish(createStr));
    *pzErr = sqlite3_mprintf(
        VEC_CONSTRUCTOR_ERROR
        "column name '%s' conflicts with table name (reserved for command "
        "column)",
        tableName);
    goto error;
  }
  sqlite3_str_appendall(createStr, " distance hidden, k hidden, ");
  if (hasCommandColumn) {
    sqlite3_str_appendf(createStr, "\"%w\" hidden, ", tableName);
  }
  sqlite3_str_appendall(createStr, "mmr_lambda hidden) ");
  if (pkColumnName) {
    sqlite3_str_appendall(createStr, "without rowid ");
  }
  zSql = sqlite3_str_finish(createStr);
  if (!zSql) {
    goto error;
  }
  rc = sqlite3_declare_vtab(db, zSql);
  sqlite3_free((void *)zSql);
  if (rc != SQLITE_OK) {
    *pzErr = sqlite3_mprintf(VEC_CONSTRUCTOR_ERROR
                             "could not declare virtual table, '%s'",
                             sqlite3_errmsg(db));
    goto error;
  }

  pNew->db = db;
  pNew->pkIsText = pkColumnType == SQLITE_TEXT;
  pNew->textEncoding = textEncoding;
  pNew->hasCommandColumn = hasCommandColumn;
  pNew->schemaName = sqlite3_mprintf("%s", schemaName);
  if (!pNew->schemaName) {
    goto error;
  }
  pNew->tableName = sqlite3_mprintf("%s", tableName);
  if (!pNew->tableName) {
    goto error;
  }
  pNew->shadowRowidsName = sqlite3_mprintf("%s_rowids", tableName);
  if (!pNew->shadowRowidsName) {
    goto error;
  }
  pNew->shadowChunksName = sqlite3_mprintf("%s_chunks", tableName);
  if (!pNew->shadowChunksName) {
    goto error;
  }
  pNew->numVectorColumns = numVectorColumns;
  pNew->numPartitionColumns = numPartitionColumns;
  pNew->numAuxiliaryColumns = numAuxiliaryColumns;
  pNew->numMetadataColumns = numMetadataColumns;

  for (int i = 0; i < pNew->numVectorColumns; i++) {
    pNew->shadowVectorChunksNames[i] =
        sqlite3_mprintf("%s_vector_chunks%02d", tableName, i);
    if (!pNew->shadowVectorChunksNames[i]) {
      goto error;
    }
  }
  for (int i = 0; i < pNew->numMetadataColumns; i++) {
    pNew->shadowMetadataChunksNames[i] =
        sqlite3_mprintf("%s_metadatachunks%02d", tableName, i);
    if (!pNew->shadowMetadataChunksNames[i]) {
      goto error;
    }
  }
  pNew->chunk_size = chunk_size;

  // if xCreate, then create the necessary shadow tables
  if (isCreate) {
    sqlite3_stmt *stmt;
    int rc;

    char *zCreateInfo = sqlite3_mprintf("CREATE TABLE " VEC0_SHADOW_INFO_NAME
                                        " (key text primary key, value any)",
                                        pNew->schemaName, pNew->tableName);
    if (!zCreateInfo) {
      goto error;
    }
    rc = sqlite3_prepare_v2(db, zCreateInfo, -1, &stmt, NULL);

    sqlite3_free((void *)zCreateInfo);
    if ((rc != SQLITE_OK) || (sqlite3_step(stmt) != SQLITE_DONE)) {
      // TODO(IMP)
      sqlite3_finalize(stmt);
      *pzErr = sqlite3_mprintf("Could not create '_info' shadow table: %s",
                               sqlite3_errmsg(db));
      goto error;
    }
    sqlite3_finalize(stmt);

    char *zSeedInfo = sqlite3_mprintf("INSERT INTO " VEC0_SHADOW_INFO_NAME
                                      "(key, value) VALUES "
                                      "(?1, ?2), (?3, ?4), (?5, ?6), (?7, ?8) ",
                                      pNew->schemaName, pNew->tableName);
    if (!zSeedInfo) {
      goto error;
    }
    rc = sqlite3_prepare_v2(db, zSeedInfo, -1, &stmt, NULL);
    sqlite3_free((void *)zSeedInfo);
    if (rc != SQLITE_OK) {
      // TODO(IMP)
      sqlite3_finalize(stmt);
      *pzErr = sqlite3_mprintf("Could not seed '_info' shadow table: %s",
                               sqlite3_errmsg(db));
      goto error;
    }
    sqlite3_bind_text(stmt, 1, "CREATE_VERSION", -1, SQLITE_STATIC);
    sqlite3_bind_text(stmt, 2, SQLITE_VEC_VERSION, -1, SQLITE_STATIC);
    sqlite3_bind_text(stmt, 3, "CREATE_VERSION_MAJOR", -1, SQLITE_STATIC);
    sqlite3_bind_int(stmt, 4, SQLITE_VEC_VERSION_MAJOR);
    sqlite3_bind_text(stmt, 5, "CREATE_VERSION_MINOR", -1, SQLITE_STATIC);
    sqlite3_bind_int(stmt, 6, SQLITE_VEC_VERSION_MINOR);
    sqlite3_bind_text(stmt, 7, "CREATE_VERSION_PATCH", -1, SQLITE_STATIC);
    sqlite3_bind_int(stmt, 8, SQLITE_VEC_VERSION_PATCH);

    if (sqlite3_step(stmt) != SQLITE_DONE) {
      // TODO(IMP)
      sqlite3_finalize(stmt);
      *pzErr = sqlite3_mprintf("Could not seed '_info' shadow table: %s",
                               sqlite3_errmsg(db));
      goto error;
    }
    sqlite3_finalize(stmt);

    // create the _chunks shadow table
    char *zCreateShadowChunks = NULL;
    if (pNew->numPartitionColumns) {
      sqlite3_str *s = sqlite3_str_new(NULL);
      sqlite3_str_appendf(s, "CREATE TABLE " VEC0_SHADOW_CHUNKS_NAME "(",
                          pNew->schemaName, pNew->tableName);
      sqlite3_str_appendall(s, "chunk_id INTEGER PRIMARY KEY AUTOINCREMENT,"
                               "size INTEGER NOT NULL,");
      sqlite3_str_appendall(s, "sequence_id integer,");
      for (int i = 0; i < pNew->numPartitionColumns; i++) {
        sqlite3_str_appendf(s, "partition%02d,", i);
      }
      sqlite3_str_appendall(s,
                            "validity BLOB NOT NULL, rowids BLOB NOT NULL);");
      zCreateShadowChunks = sqlite3_str_finish(s);
    } else {
      zCreateShadowChunks = sqlite3_mprintf(VEC0_SHADOW_CHUNKS_CREATE,
                                            pNew->schemaName, pNew->tableName);
    }
    if (!zCreateShadowChunks) {
      goto error;
    }
    rc = sqlite3_prepare_v2(db, zCreateShadowChunks, -1, &stmt, 0);
    sqlite3_free((void *)zCreateShadowChunks);
    if ((rc != SQLITE_OK) || (sqlite3_step(stmt) != SQLITE_DONE)) {
      // IMP: V17740_01811
      sqlite3_finalize(stmt);
      *pzErr = sqlite3_mprintf("Could not create '_chunks' shadow table: %s",
                               sqlite3_errmsg(db));
      goto error;
    }
    sqlite3_finalize(stmt);

    // create the _rowids shadow table
    char *zCreateShadowRowids;
    if (pNew->pkIsText) {
      // adds a "text unique not null" constraint to the id column
      zCreateShadowRowids = sqlite3_mprintf(VEC0_SHADOW_ROWIDS_CREATE_PK_TEXT,
                                            pNew->schemaName, pNew->tableName);
    } else {
      zCreateShadowRowids = sqlite3_mprintf(VEC0_SHADOW_ROWIDS_CREATE_BASIC,
                                            pNew->schemaName, pNew->tableName);
    }
    if (!zCreateShadowRowids) {
      goto error;
    }
    rc = sqlite3_prepare_v2(db, zCreateShadowRowids, -1, &stmt, 0);
    sqlite3_free((void *)zCreateShadowRowids);
    if ((rc != SQLITE_OK) || (sqlite3_step(stmt) != SQLITE_DONE)) {
      // IMP: V11631_28470
      sqlite3_finalize(stmt);
      *pzErr = sqlite3_mprintf("Could not create '_rowids' shadow table: %s",
                               sqlite3_errmsg(db));
      goto error;
    }
    sqlite3_finalize(stmt);

    for (int i = 0; i < pNew->numVectorColumns; i++) {
      char *zSql = sqlite3_mprintf(VEC0_SHADOW_VECTOR_N_CREATE,
                                   pNew->schemaName, pNew->tableName, i);
      if (!zSql) {
        goto error;
      }
      rc = sqlite3_prepare_v2(db, zSql, -1, &stmt, 0);
      sqlite3_free((void *)zSql);
      if ((rc != SQLITE_OK) || (sqlite3_step(stmt) != SQLITE_DONE)) {
        // IMP: V25919_09989
        sqlite3_finalize(stmt);
        *pzErr = sqlite3_mprintf(
            "Could not create '_vector_chunks%02d' shadow table: %s", i,
            sqlite3_errmsg(db));
        goto error;
      }
      sqlite3_finalize(stmt);
    }

    for (int i = 0; i < pNew->numMetadataColumns; i++) {
      char *zSql =
          sqlite3_mprintf("CREATE TABLE " VEC0_SHADOW_METADATA_N_NAME
                          "(rowid INTEGER PRIMARY KEY, data BLOB NOT NULL);",
                          pNew->schemaName, pNew->tableName, i);
      if (!zSql) {
        goto error;
      }
      rc = sqlite3_prepare_v2(db, zSql, -1, &stmt, 0);
      sqlite3_free((void *)zSql);
      if ((rc != SQLITE_OK) || (sqlite3_step(stmt) != SQLITE_DONE)) {
        sqlite3_finalize(stmt);
        *pzErr = sqlite3_mprintf(
            "Could not create '_metata_chunks%02d' shadow table: %s", i,
            sqlite3_errmsg(db));
        goto error;
      }
      sqlite3_finalize(stmt);

      if (pNew->metadata_columns[i].kind == VEC0_METADATA_COLUMN_KIND_TEXT) {
        char *zSql =
            sqlite3_mprintf("CREATE TABLE " VEC0_SHADOW_METADATA_TEXT_DATA_NAME
                            "(rowid PRIMARY KEY, data TEXT);",
                            pNew->schemaName, pNew->tableName, i);
        if (!zSql) {
          goto error;
        }
        rc = sqlite3_prepare_v2(db, zSql, -1, &stmt, 0);
        sqlite3_free((void *)zSql);
        if ((rc != SQLITE_OK) || (sqlite3_step(stmt) != SQLITE_DONE)) {
          sqlite3_finalize(stmt);
          *pzErr = sqlite3_mprintf(
              "Could not create '_metadatatext%02d' shadow table: %s", i,
              sqlite3_errmsg(db));
          goto error;
        }
        sqlite3_finalize(stmt);
      }
    }

    if (pNew->numAuxiliaryColumns > 0) {
      sqlite3_stmt *stmt;
      sqlite3_str *s = sqlite3_str_new(NULL);
      sqlite3_str_appendf(s,
                          "CREATE TABLE " VEC0_SHADOW_AUXILIARY_NAME
                          "( rowid integer PRIMARY KEY ",
                          pNew->schemaName, pNew->tableName);
      for (int i = 0; i < pNew->numAuxiliaryColumns; i++) {
        sqlite3_str_appendf(s, ", value%02d", i);
      }
      sqlite3_str_appendall(s, ")");
      char *zSql = sqlite3_str_finish(s);
      if (!zSql) {
        goto error;
      }
      rc = sqlite3_prepare_v2(db, zSql, -1, &stmt, NULL);
      if ((rc != SQLITE_OK) || (sqlite3_step(stmt) != SQLITE_DONE)) {
        sqlite3_finalize(stmt);
        sqlite3_free(zSql);
        *pzErr = sqlite3_mprintf("Could not create auxiliary shadow table: %s",
                                 sqlite3_errmsg(db));

        goto error;
      }
      sqlite3_free(zSql);
      sqlite3_finalize(stmt);
    }
  }

  *ppVtab = (sqlite3_vtab *)pNew;
  return SQLITE_OK;

error:
  // Column names are copied into pNew while parsing, before the pNew->num*
  // counters are assigned; set them so vec0_free() frees those names.
  pNew->numVectorColumns = numVectorColumns;
  pNew->numPartitionColumns = numPartitionColumns;
  pNew->numAuxiliaryColumns = numAuxiliaryColumns;
  pNew->numMetadataColumns = numMetadataColumns;
  vec0_free(pNew);
  return SQLITE_ERROR;
}

static int vec0Create(sqlite3 *db, void *pAux, int argc,
                      const char *const *argv, sqlite3_vtab **ppVtab,
                      char **pzErr) {
  return vec0_init(db, pAux, argc, argv, ppVtab, pzErr, true);
}
static int vec0Connect(sqlite3 *db, void *pAux, int argc,
                       const char *const *argv, sqlite3_vtab **ppVtab,
                       char **pzErr) {
  return vec0_init(db, pAux, argc, argv, ppVtab, pzErr, false);
}

static int vec0Disconnect(sqlite3_vtab *pVtab) {
  vec0_vtab *p = (vec0_vtab *)pVtab;
  vec0_free(p);
  return SQLITE_OK;
}
static int vec0Destroy(sqlite3_vtab *pVtab) {
  vec0_vtab *p = (vec0_vtab *)pVtab;
  sqlite3_stmt *stmt;
  int rc;
  const char *zSql;

  // Free up any sqlite3_stmt, otherwise DROPs on those tables will fail
  vec0_free_resources(p);

  // SQLite never reports a message set here (OP_VDestroy ignores zErrMsg), and
  // on a table that survives a failed xDestroy the message could leak, so set
  // none.
  zSql = sqlite3_mprintf("DROP TABLE " VEC0_SHADOW_CHUNKS_NAME, p->schemaName,
                         p->tableName);
  rc = sqlite3_prepare_v2(p->db, zSql, -1, &stmt, 0);
  sqlite3_free((void *)zSql);
  if ((rc != SQLITE_OK) || (sqlite3_step(stmt) != SQLITE_DONE)) {
    rc = SQLITE_ERROR;
    goto done;
  }
  sqlite3_finalize(stmt);

  zSql = sqlite3_mprintf("DROP TABLE " VEC0_SHADOW_INFO_NAME, p->schemaName,
                         p->tableName);
  rc = sqlite3_prepare_v2(p->db, zSql, -1, &stmt, 0);
  sqlite3_free((void *)zSql);
  if ((rc != SQLITE_OK) || (sqlite3_step(stmt) != SQLITE_DONE)) {
    rc = SQLITE_ERROR;
    goto done;
  }
  sqlite3_finalize(stmt);

  zSql = sqlite3_mprintf("DROP TABLE " VEC0_SHADOW_ROWIDS_NAME, p->schemaName,
                         p->tableName);
  rc = sqlite3_prepare_v2(p->db, zSql, -1, &stmt, 0);
  sqlite3_free((void *)zSql);
  if ((rc != SQLITE_OK) || (sqlite3_step(stmt) != SQLITE_DONE)) {
    rc = SQLITE_ERROR;
    goto done;
  }
  sqlite3_finalize(stmt);

  for (int i = 0; i < p->numVectorColumns; i++) {
    zSql = sqlite3_mprintf("DROP TABLE \"%w\".\"%w\"", p->schemaName,
                           p->shadowVectorChunksNames[i]);
    rc = sqlite3_prepare_v2(p->db, zSql, -1, &stmt, 0);
    sqlite3_free((void *)zSql);
    if ((rc != SQLITE_OK) || (sqlite3_step(stmt) != SQLITE_DONE)) {
      rc = SQLITE_ERROR;
      goto done;
    }
    sqlite3_finalize(stmt);
  }

  if (p->numAuxiliaryColumns > 0) {
    zSql = sqlite3_mprintf("DROP TABLE " VEC0_SHADOW_AUXILIARY_NAME,
                           p->schemaName, p->tableName);
    rc = sqlite3_prepare_v2(p->db, zSql, -1, &stmt, 0);
    sqlite3_free((void *)zSql);
    if ((rc != SQLITE_OK) || (sqlite3_step(stmt) != SQLITE_DONE)) {
      rc = SQLITE_ERROR;
      goto done;
    }
    sqlite3_finalize(stmt);
  }

  for (int i = 0; i < p->numMetadataColumns; i++) {
    zSql = sqlite3_mprintf("DROP TABLE " VEC0_SHADOW_METADATA_N_NAME,
                           p->schemaName, p->tableName, i);
    rc = sqlite3_prepare_v2(p->db, zSql, -1, &stmt, 0);
    sqlite3_free((void *)zSql);
    if ((rc != SQLITE_OK) || (sqlite3_step(stmt) != SQLITE_DONE)) {
      rc = SQLITE_ERROR;
      goto done;
    }
    sqlite3_finalize(stmt);

    if (p->metadata_columns[i].kind == VEC0_METADATA_COLUMN_KIND_TEXT) {
      zSql = sqlite3_mprintf("DROP TABLE " VEC0_SHADOW_METADATA_TEXT_DATA_NAME,
                             p->schemaName, p->tableName, i);
      rc = sqlite3_prepare_v2(p->db, zSql, -1, &stmt, 0);
      sqlite3_free((void *)zSql);
      if ((rc != SQLITE_OK) || (sqlite3_step(stmt) != SQLITE_DONE)) {
        rc = SQLITE_ERROR;
        goto done;
      }
      sqlite3_finalize(stmt);
    }
  }

  stmt = NULL;
  rc = SQLITE_OK;

done:
  sqlite3_finalize(stmt);
  // SQLite keeps a table whose xDestroy fails, and later calls its other
  // methods and xDisconnect, so free it only on success.
  if (rc == SQLITE_OK) {
    vec0_free(p);
  }
  return rc;
}

static int vec0Open(sqlite3_vtab *p, sqlite3_vtab_cursor **ppCursor) {
  UNUSED_PARAMETER(p);
  vec0_cursor *pCur;
  pCur = sqlite3_malloc(sizeof(*pCur));
  if (pCur == 0)
    return SQLITE_NOMEM;
  memset(pCur, 0, sizeof(*pCur));
  *ppCursor = &pCur->base;
  return SQLITE_OK;
}

static int vec0Close(sqlite3_vtab_cursor *cur) {
  vec0_cursor *pCur = (vec0_cursor *)cur;
  vec0_cursor_clear(pCur);
  sqlite3_free(pCur);
  return SQLITE_OK;
}

// All the different type of "values" provided to argv/argc in vec0Filter.
// These enums denote the use and purpose of all of them.
typedef enum {
  // If any values are updated, please update the ARCHITECTURE.md docs
  // accordingly!

  // ~~~ KNN QUERIES ~~~ //
  VEC0_IDXSTR_KIND_KNN_MATCH = '{',
  VEC0_IDXSTR_KIND_KNN_K = '}',
  VEC0_IDXSTR_KIND_KNN_ROWID_IN = '[',
  // argv[i] is the value of a `rowid = ?` constraint in a KNN query
  VEC0_IDXSTR_KIND_KNN_ROWID_EQ = '=',
  // argv[i] is a constraint on a PARTITON KEY column in a KNN query
  //
  VEC0_IDXSTR_KIND_KNN_PARTITON_CONSTRAINT = ']',

  // argv[i] is a constraint on the distance column in a KNN query
  VEC0_IDXSTR_KIND_KNN_DISTANCE_CONSTRAINT = '*',

  // ~~~ POINT QUERIES ~~~ //
  VEC0_IDXSTR_KIND_POINT_ID = '!',

  // ~~~ KNN QUERIES, continued ~~~ //
  VEC0_IDXSTR_KIND_METADATA_CONSTRAINT = '&',
  VEC0_IDXSTR_KIND_KNN_MMR_LAMBDA = '#',
} vec0_idxstr_kind;

// The different SQLITE_INDEX_CONSTRAINT values that vec0 partition key columns
// support, but as characters that fit nicely in idxstr.
typedef enum {
  // If any values are updated, please update the ARCHITECTURE.md docs
  // accordingly!

  // Equality constraint on a PARTITON KEY column, ex `user_id = 123`
  VEC0_PARTITION_OPERATOR_EQ = 'a',

  // "Greater than" constraint on a PARTITON KEY column, ex `year > 2024`
  VEC0_PARTITION_OPERATOR_GT = 'b',

  // "Less than or equal to" constraint on a PARTITON KEY column, ex `year <=
  // 2024`
  VEC0_PARTITION_OPERATOR_LE = 'c',

  // "Less than" constraint on a PARTITON KEY column, ex `year < 2024`
  VEC0_PARTITION_OPERATOR_LT = 'd',

  // "Greater than or equal to" constraint on a PARTITON KEY column, ex `year >=
  // 2024`
  VEC0_PARTITION_OPERATOR_GE = 'e',

  // "Not equal to" constraint on a PARTITON KEY column, ex `year != 2024`
  VEC0_PARTITION_OPERATOR_NE = 'f',

  // `user_id in (...)`, whose values are read with sqlite3_vtab_in_first()
  VEC0_PARTITION_OPERATOR_IN = 'g',
  VEC0_PARTITION_OPERATOR_LIKE = 'h',
  VEC0_PARTITION_OPERATOR_GLOB = 'i',
  VEC0_PARTITION_OPERATOR_IS = 'j',
  VEC0_PARTITION_OPERATOR_ISNOT = 'k',
  VEC0_PARTITION_OPERATOR_ISNULL = 'l',
  VEC0_PARTITION_OPERATOR_ISNOTNULL = 'm',
} vec0_partition_operator;
typedef enum {
  VEC0_METADATA_OPERATOR_EQ = 'a',
  VEC0_METADATA_OPERATOR_GT = 'b',
  VEC0_METADATA_OPERATOR_LE = 'c',
  VEC0_METADATA_OPERATOR_LT = 'd',
  VEC0_METADATA_OPERATOR_GE = 'e',
  VEC0_METADATA_OPERATOR_NE = 'f',
  VEC0_METADATA_OPERATOR_IN = 'g',
  VEC0_METADATA_OPERATOR_LIKE = 'h',
  VEC0_METADATA_OPERATOR_GLOB = 'i',
  VEC0_METADATA_OPERATOR_IS = 'j',
  VEC0_METADATA_OPERATOR_ISNOT = 'k',
  VEC0_METADATA_OPERATOR_ISNULL = 'l',
  VEC0_METADATA_OPERATOR_ISNOTNULL = 'm',
} vec0_metadata_operator;

// The collation a KNN query's text metadata filter compares with. If any values
// are updated, please update the ARCHITECTURE.md docs accordingly!
typedef enum {
  VEC0_METADATA_COLLATION_BINARY = '_',
  VEC0_METADATA_COLLATION_NOCASE = 'n',
  VEC0_METADATA_COLLATION_RTRIM = 'r',
} vec0_metadata_collation;

typedef enum {

  VEC0_DISTANCE_CONSTRAINT_GT = 'a',
  VEC0_DISTANCE_CONSTRAINT_GE = 'b',
  VEC0_DISTANCE_CONSTRAINT_LT = 'c',
  VEC0_DISTANCE_CONSTRAINT_LE = 'd',
} vec0_distance_constraint_operator;

/**
 * Whether constraint i is an argument of a KNN query: a MATCH on a vector
 * column, `k = ?`, or `mmr_lambda = ?`. Filters are not refused;
 * ARCHITECTURE.md's idxStr section says why, and when a filter whose value
 * comes from another table applies before the k anyway.
 */
static int vec0_constraint_is_knn_argument(vec0_vtab *p,
                                           sqlite3_index_info *pIdxInfo,
                                           int i) {
  int iColumn = pIdxInfo->aConstraint[i].iColumn;
  int op = pIdxInfo->aConstraint[i].op;
  if (op == SQLITE_INDEX_CONSTRAINT_MATCH) {
    return vec0_column_idx_is_vector(p, iColumn);
  }
  return op == SQLITE_INDEX_CONSTRAINT_EQ &&
         (iColumn == vec0_column_k_idx(p) ||
          iColumn == vec0_column_mmr_lambda_idx(p));
}

static int vec0BestIndex(sqlite3_vtab *pVTab, sqlite3_index_info *pIdxInfo) {
  vec0_vtab *p = (vec0_vtab *)pVTab;
  /**
   * Possible query plans are:
   * 1. KNN when:
   *    a) An `MATCH` op on vector column
   *    b) ORDER BY on distance column
   *    c) LIMIT
   *    d) rowid = ? or rowid in (...) OPTIONAL
   * 2. Point when:
   *    a) An `EQ` op on rowid column
   * 3. else: fullscan
   *
   */
  int iMatchTerm = -1;
  int iMatchVectorTerm = -1;
  int iLimitTerm = -1;
  int iRowidTerm = -1;
  int iKTerm = -1;
  int iMmrLambdaTerm = -1;
  int iRowidInTerm = -1;
  int hasAuxConstraint = 0;

#ifdef SQLITE_VEC_DEBUG
  printf("pIdxInfo->nOrderBy=%d, pIdxInfo->nConstraint=%d\n",
         pIdxInfo->nOrderBy, pIdxInfo->nConstraint);
#endif

  // When a KNN argument reads another table of the query, SQLite also weighs
  // plans that scan vec0 before that table, in which the argument is unusable.
  // Such a plan is refused, the way json_each refuses a plan that cannot supply
  // its argument, so the planner takes one that gives vec0 every argument.
  for (int i = 0; i < pIdxInfo->nConstraint; i++) {
    if (pIdxInfo->aConstraint[i].op == SQLITE_INDEX_CONSTRAINT_MATCH &&
        vec0_column_idx_is_vector(p, pIdxInfo->aConstraint[i].iColumn)) {
      for (int j = 0; j < pIdxInfo->nConstraint; j++) {
        if (!pIdxInfo->aConstraint[j].usable &&
            vec0_constraint_is_knn_argument(p, pIdxInfo, j)) {
          return SQLITE_CONSTRAINT;
        }
      }
      break;
    }
  }

  for (int i = 0; i < pIdxInfo->nConstraint; i++) {
    u8 vtabIn = 0;

#if COMPILER_SUPPORTS_VTAB_IN
    if (sqlite3_libversion_number() >= 3038000) {
      vtabIn = sqlite3_vtab_in(pIdxInfo, i, -1);
    }
#endif

#ifdef SQLITE_VEC_DEBUG
    printf("xBestIndex [%d] usable=%d iColumn=%d op=%d vtabin=%d\n", i,
           pIdxInfo->aConstraint[i].usable, pIdxInfo->aConstraint[i].iColumn,
           pIdxInfo->aConstraint[i].op, vtabIn);
#endif
    if (!pIdxInfo->aConstraint[i].usable)
      continue;

    int iColumn = pIdxInfo->aConstraint[i].iColumn;
    int op = pIdxInfo->aConstraint[i].op;

    if (op == SQLITE_INDEX_CONSTRAINT_LIMIT) {
      iLimitTerm = i;
    }
    if (op == SQLITE_INDEX_CONSTRAINT_MATCH &&
        vec0_column_idx_is_vector(p, iColumn)) {
      if (iMatchTerm > -1) {
        vtab_set_error(
            pVTab, "only 1 MATCH operator is allowed in a single vec0 query");
        return SQLITE_ERROR;
      }
      iMatchTerm = i;
      iMatchVectorTerm = vec0_column_idx_to_vector_idx(p, iColumn);
    }
    if (op == SQLITE_INDEX_CONSTRAINT_EQ && iColumn == VEC0_COLUMN_ID) {
      if (vtabIn) {
        if (iRowidInTerm != -1) {
          vtab_set_error(pVTab, "only 1 'rowid in (..)' operator is allowed in "
                                "a single vec0 query");
          return SQLITE_ERROR;
        }
        iRowidInTerm = i;

      } else {
        iRowidTerm = i;
      }
    }
    if (op == SQLITE_INDEX_CONSTRAINT_EQ && iColumn == vec0_column_k_idx(p)) {
      iKTerm = i;
    }
    if (op == SQLITE_INDEX_CONSTRAINT_EQ &&
        iColumn == vec0_column_mmr_lambda_idx(p)) {
      iMmrLambdaTerm = i;
    }
    if ((op != SQLITE_INDEX_CONSTRAINT_LIMIT &&
         op != SQLITE_INDEX_CONSTRAINT_OFFSET) &&
        vec0_column_idx_is_auxiliary(p, iColumn)) {
      hasAuxConstraint = 1;
    }
  }

  sqlite3_str *idxStr = sqlite3_str_new(NULL);
  int rc;

  if (iMatchTerm >= 0) {
    if (iLimitTerm < 0 && iKTerm < 0) {
      vtab_set_error(
          pVTab,
          "A LIMIT or 'k = ?' constraint is required on vec0 knn queries.");
      rc = SQLITE_ERROR;
      goto done;
    }
    if (iLimitTerm >= 0 && iKTerm >= 0) {
      vtab_set_error(pVTab, "Only LIMIT or 'k =?' can be provided, not both");
      rc = SQLITE_ERROR;
      goto done;
    }

    if (pIdxInfo->nOrderBy) {
      if (pIdxInfo->nOrderBy > 1) {
        vtab_set_error(pVTab, "Only a single 'ORDER BY distance' clause is "
                              "allowed on vec0 KNN queries");
        rc = SQLITE_ERROR;
        goto done;
      }
      if (pIdxInfo->aOrderBy[0].iColumn != vec0_column_distance_idx(p)) {
        vtab_set_error(pVTab,
                       "Only a single 'ORDER BY distance' clause is allowed on "
                       "vec0 KNN queries, not on other columns");
        rc = SQLITE_ERROR;
        goto done;
      }
      if (pIdxInfo->aOrderBy[0].desc) {
        vtab_set_error(
            pVTab, "Only ascending in ORDER BY distance clause is supported, "
                   "DESC is not supported yet.");
        rc = SQLITE_ERROR;
        goto done;
      }
    }

    if (hasAuxConstraint) {
      // IMP: V25623_09693
      vtab_set_error(pVTab, "An illegal WHERE constraint was provided on a "
                            "vec0 auxiliary column in a KNN query.");
      rc = SQLITE_ERROR;
      goto done;
    }

    sqlite3_str_appendchar(idxStr, 1, VEC0_QUERY_PLAN_KNN);

    int argvIndex = 1;
    pIdxInfo->aConstraintUsage[iMatchTerm].argvIndex = argvIndex++;
    pIdxInfo->aConstraintUsage[iMatchTerm].omit = 1;
    sqlite3_str_appendchar(idxStr, 1, VEC0_IDXSTR_KIND_KNN_MATCH);
    sqlite3_str_appendchar(idxStr, 3, '_');

    if (iLimitTerm >= 0) {
      pIdxInfo->aConstraintUsage[iLimitTerm].argvIndex = argvIndex++;
      pIdxInfo->aConstraintUsage[iLimitTerm].omit = 1;
    } else {
      pIdxInfo->aConstraintUsage[iKTerm].argvIndex = argvIndex++;
      pIdxInfo->aConstraintUsage[iKTerm].omit = 1;
    }
    sqlite3_str_appendchar(idxStr, 1, VEC0_IDXSTR_KIND_KNN_K);
    sqlite3_str_appendchar(idxStr, 3, '_');

    // SQLite passes a one-value `rowid in (?)` as `rowid = ?`. vec0 looks up a
    // text id with BINARY, so it leaves an id compared with another collation
    // to SQLite. With both forms, vec0 looks up the `=` value and SQLite checks
    // the list.
    if (iRowidTerm >= 0 &&
        (!p->pkIsText ||
         sqlite3_stricmp(sqlite3_vtab_collation(pIdxInfo, iRowidTerm),
                         "BINARY") == 0)) {
      pIdxInfo->aConstraintUsage[iRowidTerm].argvIndex = argvIndex++;
      pIdxInfo->aConstraintUsage[iRowidTerm].omit = 1;
      sqlite3_str_appendchar(idxStr, 1, VEC0_IDXSTR_KIND_KNN_ROWID_EQ);
      sqlite3_str_appendchar(idxStr, 3, '_');
#if COMPILER_SUPPORTS_VTAB_IN
    } else if (iRowidInTerm >= 0) {
      // already validated as  >= SQLite 3.38 bc iRowidInTerm is only >= 0 when
      // vtabIn == 1
      sqlite3_vtab_in(pIdxInfo, iRowidInTerm, 1);
      pIdxInfo->aConstraintUsage[iRowidInTerm].argvIndex = argvIndex++;
      pIdxInfo->aConstraintUsage[iRowidInTerm].omit = 1;
      sqlite3_str_appendchar(idxStr, 1, VEC0_IDXSTR_KIND_KNN_ROWID_IN);
      sqlite3_str_appendchar(idxStr, 3, '_');
#endif
    }

    // find any PARTITION KEY column constraints
    for (int i = 0; i < pIdxInfo->nConstraint; i++) {
      if (!pIdxInfo->aConstraint[i].usable)
        continue;

      int iColumn = pIdxInfo->aConstraint[i].iColumn;
      int op = pIdxInfo->aConstraint[i].op;
      if (op == SQLITE_INDEX_CONSTRAINT_LIMIT ||
          op == SQLITE_INDEX_CONSTRAINT_OFFSET) {
        continue;
      }
      if (!vec0_column_idx_is_partition(p, iColumn)) {
        continue;
      }

      int partition_idx = vec0_column_idx_to_partition_idx(p, iColumn);
      char value = 0;
      int omit = 1;
      // An IN or IS that names a collation other than BINARY keeps the handling
      // it had before vec0 consumed them: an IN stays an `=` that SQLite runs
      // once per value, and SQLite applies an IS to the rows vec0 returns.
      int isBinary =
          sqlite3_stricmp(sqlite3_vtab_collation(pIdxInfo, i), "BINARY") == 0;

      switch (op) {
      case SQLITE_INDEX_CONSTRAINT_EQ: {
        value = VEC0_PARTITION_OPERATOR_EQ;
#if COMPILER_SUPPORTS_VTAB_IN
        if (isBinary && sqlite3_libversion_number() >= 3038000 &&
            sqlite3_vtab_in(pIdxInfo, i, -1)) {
          sqlite3_vtab_in(pIdxInfo, i, 1);
          value = VEC0_PARTITION_OPERATOR_IN;
        }
#endif
        break;
      }
      case SQLITE_INDEX_CONSTRAINT_GT: {
        value = VEC0_PARTITION_OPERATOR_GT;
        break;
      }
      case SQLITE_INDEX_CONSTRAINT_LE: {
        value = VEC0_PARTITION_OPERATOR_LE;
        break;
      }
      case SQLITE_INDEX_CONSTRAINT_LT: {
        value = VEC0_PARTITION_OPERATOR_LT;
        break;
      }
      case SQLITE_INDEX_CONSTRAINT_GE: {
        value = VEC0_PARTITION_OPERATOR_GE;
        break;
      }
      case SQLITE_INDEX_CONSTRAINT_NE: {
        value = VEC0_PARTITION_OPERATOR_NE;
        break;
      }
      case SQLITE_INDEX_CONSTRAINT_LIKE: {
        value = VEC0_PARTITION_OPERATOR_LIKE;
        break;
      }
      case SQLITE_INDEX_CONSTRAINT_GLOB: {
        value = VEC0_PARTITION_OPERATOR_GLOB;
        break;
      }
      case SQLITE_INDEX_CONSTRAINT_IS: {
        if (isBinary) {
          value = VEC0_PARTITION_OPERATOR_IS;
        }
        break;
      }
      case SQLITE_INDEX_CONSTRAINT_ISNOT: {
        value = VEC0_PARTITION_OPERATOR_ISNOT;
        // SQLite reports BINARY for IS NOT whatever collation the query names,
        // so vec0 compares bytewise and SQLite re-checks each row
        omit = 0;
        break;
      }
      case SQLITE_INDEX_CONSTRAINT_ISNULL: {
        value = VEC0_PARTITION_OPERATOR_ISNULL;
        break;
      }
      case SQLITE_INDEX_CONSTRAINT_ISNOTNULL: {
        value = VEC0_PARTITION_OPERATOR_ISNOTNULL;
        break;
      }
      }

      // The _chunks query compares a text key under the collation the query
      // names, as the metadata constraints below do. SQLite reports BINARY for
      // != whatever collation the query names, so vec0 compares it bytewise
      // and SQLite re-checks each row, as for IS NOT.
      char collation = VEC0_METADATA_COLLATION_BINARY;
      if (value && p->paritition_columns[partition_idx].type == SQLITE_TEXT) {
        switch (value) {
        case VEC0_PARTITION_OPERATOR_EQ:
        case VEC0_PARTITION_OPERATOR_GT:
        case VEC0_PARTITION_OPERATOR_LE:
        case VEC0_PARTITION_OPERATOR_LT:
        case VEC0_PARTITION_OPERATOR_GE: {
          const char *zCollation = sqlite3_vtab_collation(pIdxInfo, i);
          if (sqlite3_stricmp(zCollation, "NOCASE") == 0) {
            collation = VEC0_METADATA_COLLATION_NOCASE;
          } else if (sqlite3_stricmp(zCollation, "RTRIM") == 0) {
            collation = VEC0_METADATA_COLLATION_RTRIM;
          } else if (sqlite3_stricmp(zCollation, "BINARY") != 0) {
            rc = SQLITE_ERROR;
            vtab_set_error(pVTab,
                           "Collation \"%s\" is not supported on the \"%.*s\" "
                           "partition key in a vec0 KNN query. Only BINARY, "
                           "NOCASE, and RTRIM are supported.",
                           zCollation,
                           p->paritition_columns[partition_idx].name_length,
                           p->paritition_columns[partition_idx].name);
            goto done;
          }
          break;
        }
        case VEC0_PARTITION_OPERATOR_NE: {
          omit = 0;
          break;
        }
        }
      }

      if (value) {
        pIdxInfo->aConstraintUsage[i].argvIndex = argvIndex++;
        pIdxInfo->aConstraintUsage[i].omit = omit;
        sqlite3_str_appendchar(idxStr, 1,
                               VEC0_IDXSTR_KIND_KNN_PARTITON_CONSTRAINT);
        sqlite3_str_appendchar(idxStr, 1, 'A' + partition_idx);
        sqlite3_str_appendchar(idxStr, 1, value);
        sqlite3_str_appendchar(idxStr, 1, collation);
      }
    }

    // find any metadata column constraints
    for (int i = 0; i < pIdxInfo->nConstraint; i++) {
      if (!pIdxInfo->aConstraint[i].usable)
        continue;

      int iColumn = pIdxInfo->aConstraint[i].iColumn;
      int op = pIdxInfo->aConstraint[i].op;
      if (op == SQLITE_INDEX_CONSTRAINT_LIMIT ||
          op == SQLITE_INDEX_CONSTRAINT_OFFSET) {
        continue;
      }
      if (!vec0_column_idx_is_metadata(p, iColumn)) {
        continue;
      }

      int metadata_idx = vec0_column_idx_to_metadata_idx(p, iColumn);
      char value = 0;

      switch (op) {
      case SQLITE_INDEX_CONSTRAINT_EQ: {
        int vtabIn = 0;
#if COMPILER_SUPPORTS_VTAB_IN
        if (sqlite3_libversion_number() >= 3038000) {
          vtabIn = sqlite3_vtab_in(pIdxInfo, i, -1);
        }
        if (vtabIn) {
          switch (p->metadata_columns[metadata_idx].kind) {
          case VEC0_METADATA_COLUMN_KIND_FLOAT:
          case VEC0_METADATA_COLUMN_KIND_BOOLEAN: {
            // IMP: V15248_32086
            rc = SQLITE_ERROR;
            vtab_set_error(pVTab, "'xxx in (...)' is only available on INTEGER "
                                  "or TEXT metadata columns.");
            goto done;
            break;
          }
          case VEC0_METADATA_COLUMN_KIND_INTEGER:
          case VEC0_METADATA_COLUMN_KIND_TEXT: {
            break;
          }
          }
          value = VEC0_METADATA_OPERATOR_IN;
          sqlite3_vtab_in(pIdxInfo, i, 1);
        } else
#endif
        {
          value = VEC0_METADATA_OPERATOR_EQ;
        }
        break;
      }
      case SQLITE_INDEX_CONSTRAINT_GT: {
        value = VEC0_METADATA_OPERATOR_GT;
        break;
      }
      case SQLITE_INDEX_CONSTRAINT_LE: {
        value = VEC0_METADATA_OPERATOR_LE;
        break;
      }
      case SQLITE_INDEX_CONSTRAINT_LT: {
        value = VEC0_METADATA_OPERATOR_LT;
        break;
      }
      case SQLITE_INDEX_CONSTRAINT_GE: {
        value = VEC0_METADATA_OPERATOR_GE;
        break;
      }
      case SQLITE_INDEX_CONSTRAINT_NE: {
        value = VEC0_METADATA_OPERATOR_NE;
        break;
      }
      case SQLITE_INDEX_CONSTRAINT_LIKE: {
        value = VEC0_METADATA_OPERATOR_LIKE;
        break;
      }
      case SQLITE_INDEX_CONSTRAINT_GLOB: {
        value = VEC0_METADATA_OPERATOR_GLOB;
        break;
      }
      case SQLITE_INDEX_CONSTRAINT_IS: {
        value = VEC0_METADATA_OPERATOR_IS;
        break;
      }
      case SQLITE_INDEX_CONSTRAINT_ISNOT: {
        value = VEC0_METADATA_OPERATOR_ISNOT;
        break;
      }
      case SQLITE_INDEX_CONSTRAINT_ISNULL: {
        value = VEC0_METADATA_OPERATOR_ISNULL;
        break;
      }
      case SQLITE_INDEX_CONSTRAINT_ISNOTNULL: {
        value = VEC0_METADATA_OPERATOR_ISNOTNULL;
        break;
      }
      default: {
        // IMP: V16511_00582
        rc = SQLITE_ERROR;
        vtab_set_error(pVTab,
                       "An illegal WHERE constraint was provided on a vec0 "
                       "metadata column in a KNN query. "
                       "Only one of EQUALS, GREATER_THAN, LESS_THAN_OR_EQUAL, "
                       "LESS_THAN, GREATER_THAN_OR_EQUAL, NOT_EQUALS, LIKE, "
                       "GLOB, IS, IS NOT, IS NULL, IS NOT NULL is allowed.");
        goto done;
      }
      }

      if (p->metadata_columns[metadata_idx].kind ==
          VEC0_METADATA_COLUMN_KIND_BOOLEAN) {
        if (!(value == VEC0_METADATA_OPERATOR_EQ ||
              value == VEC0_METADATA_OPERATOR_NE ||
              value == VEC0_METADATA_OPERATOR_IS ||
              value == VEC0_METADATA_OPERATOR_ISNOT ||
              value == VEC0_METADATA_OPERATOR_ISNULL ||
              value == VEC0_METADATA_OPERATOR_ISNOTNULL)) {
          // IMP: V10145_26984
          rc = SQLITE_ERROR;
          vtab_set_error(
              pVTab,
              "ONLY EQUALS (=), NOT_EQUALS (!=), IS, IS NOT, IS NULL, or IS "
              "NOT NULL operators are allowed on boolean metadata columns.");
          goto done;
        }
      }

      if (value == VEC0_METADATA_OPERATOR_LIKE) {
        if (p->metadata_columns[metadata_idx].kind !=
            VEC0_METADATA_COLUMN_KIND_TEXT) {
          rc = SQLITE_ERROR;
          vtab_set_error(
              pVTab, "LIKE operator is only allowed on TEXT metadata columns.");
          goto done;
        }
      }

      if (value == VEC0_METADATA_OPERATOR_GLOB) {
        if (p->metadata_columns[metadata_idx].kind !=
            VEC0_METADATA_COLUMN_KIND_TEXT) {
          rc = SQLITE_ERROR;
          vtab_set_error(
              pVTab, "GLOB operator is only allowed on TEXT metadata columns.");
          goto done;
        }
      }

      // SQLite compares an INTEGER or REAL without a collation, so only a text
      // comparison carries one
      char collation = VEC0_METADATA_COLLATION_BINARY;
      int omit = 1;
      if (p->metadata_columns[metadata_idx].kind ==
          VEC0_METADATA_COLUMN_KIND_TEXT) {
        switch (value) {
        case VEC0_METADATA_OPERATOR_EQ:
        case VEC0_METADATA_OPERATOR_IN:
        case VEC0_METADATA_OPERATOR_GT:
        case VEC0_METADATA_OPERATOR_LE:
        case VEC0_METADATA_OPERATOR_LT:
        case VEC0_METADATA_OPERATOR_GE:
        case VEC0_METADATA_OPERATOR_IS: {
          const char *zCollation = sqlite3_vtab_collation(pIdxInfo, i);
          if (sqlite3_stricmp(zCollation, "NOCASE") == 0) {
            collation = VEC0_METADATA_COLLATION_NOCASE;
          } else if (sqlite3_stricmp(zCollation, "RTRIM") == 0) {
            collation = VEC0_METADATA_COLLATION_RTRIM;
          } else if (sqlite3_stricmp(zCollation, "BINARY") != 0) {
            rc = SQLITE_ERROR;
            vtab_set_error(pVTab,
                           "Collation \"%s\" is not supported on the \"%.*s\" "
                           "metadata column in a vec0 KNN query. Only BINARY, "
                           "NOCASE, and RTRIM are supported.",
                           zCollation,
                           p->metadata_columns[metadata_idx].name_length,
                           p->metadata_columns[metadata_idx].name);
            goto done;
          }
          break;
        }
        case VEC0_METADATA_OPERATOR_NE:
        case VEC0_METADATA_OPERATOR_ISNOT: {
          // SQLite reports BINARY for these whatever collation the query
          // names, so vec0 compares bytewise and SQLite re-checks each row
          omit = 0;
          break;
        }
        }
      }

      pIdxInfo->aConstraintUsage[i].argvIndex = argvIndex++;
      pIdxInfo->aConstraintUsage[i].omit = omit;
      sqlite3_str_appendchar(idxStr, 1, VEC0_IDXSTR_KIND_METADATA_CONSTRAINT);
      sqlite3_str_appendchar(idxStr, 1, 'A' + metadata_idx);
      sqlite3_str_appendchar(idxStr, 1, value);
      sqlite3_str_appendchar(idxStr, 1, collation);
    }

    // find any distance column constraints
    for (int i = 0; i < pIdxInfo->nConstraint; i++) {
      if (!pIdxInfo->aConstraint[i].usable)
        continue;

      int iColumn = pIdxInfo->aConstraint[i].iColumn;
      int op = pIdxInfo->aConstraint[i].op;
      if (op == SQLITE_INDEX_CONSTRAINT_LIMIT ||
          op == SQLITE_INDEX_CONSTRAINT_OFFSET) {
        continue;
      }
      if (vec0_column_distance_idx(p) != iColumn) {
        continue;
      }

      char value = 0;
      switch (op) {
      case SQLITE_INDEX_CONSTRAINT_GT: {
        value = VEC0_DISTANCE_CONSTRAINT_GT;
        break;
      }
      case SQLITE_INDEX_CONSTRAINT_GE: {
        value = VEC0_DISTANCE_CONSTRAINT_GE;
        break;
      }
      case SQLITE_INDEX_CONSTRAINT_LT: {
        value = VEC0_DISTANCE_CONSTRAINT_LT;
        break;
      }
      case SQLITE_INDEX_CONSTRAINT_LE: {
        value = VEC0_DISTANCE_CONSTRAINT_LE;
        break;
      }
      default: {
        // IMP TODO
        rc = SQLITE_ERROR;
        vtab_set_error(
            pVTab,
            "Illegal WHERE constraint on distance column in a KNN query. "
            "Only one of GT, GE, LT, LE constraints are allowed.");
        goto done;
      }
      }

      pIdxInfo->aConstraintUsage[i].argvIndex = argvIndex++;
      pIdxInfo->aConstraintUsage[i].omit = 1;
      sqlite3_str_appendchar(idxStr, 1,
                             VEC0_IDXSTR_KIND_KNN_DISTANCE_CONSTRAINT);
      sqlite3_str_appendchar(idxStr, 1, value);
      sqlite3_str_appendchar(idxStr, 1, '_');
      sqlite3_str_appendchar(idxStr, 1, '_');
    }

    if (iMmrLambdaTerm >= 0) {
      pIdxInfo->aConstraintUsage[iMmrLambdaTerm].argvIndex = argvIndex++;
      pIdxInfo->aConstraintUsage[iMmrLambdaTerm].omit = 1;
      sqlite3_str_appendchar(idxStr, 1, VEC0_IDXSTR_KIND_KNN_MMR_LAMBDA);
      sqlite3_str_appendchar(idxStr, 3, '_');
    }

    pIdxInfo->idxNum = iMatchVectorTerm;
    pIdxInfo->estimatedCost = 30.0;
    pIdxInfo->estimatedRows = 10;

  } else if (iRowidTerm >= 0) {
    sqlite3_str_appendchar(idxStr, 1, VEC0_QUERY_PLAN_POINT);
    pIdxInfo->aConstraintUsage[iRowidTerm].argvIndex = 1;
    // vec0 looks a text id up in _rowids.id, which is declared TEXT, so the
    // integer 5 finds '5'. The id column is declared without a type, so SQLite
    // re-checks the row with the affinity of the other side: `id = 5` keeps no
    // row, and `id = x` with x declared INTEGER keeps '5'.
    pIdxInfo->aConstraintUsage[iRowidTerm].omit = !p->pkIsText;
    sqlite3_str_appendchar(idxStr, 1, VEC0_IDXSTR_KIND_POINT_ID);
    sqlite3_str_appendchar(idxStr, 3, '_');
    pIdxInfo->idxNum = pIdxInfo->colUsed;
    pIdxInfo->estimatedCost = 10.0;
    pIdxInfo->estimatedRows = 1;
  } else {
    sqlite3_str_appendchar(idxStr, 1, VEC0_QUERY_PLAN_FULLSCAN);
    pIdxInfo->estimatedCost = 3000000.0;
    pIdxInfo->estimatedRows = 100000;
  }
  pIdxInfo->idxStr = sqlite3_str_finish(idxStr);
  idxStr = NULL;
  if (!pIdxInfo->idxStr) {
    rc = SQLITE_OK;
    goto done;
  }
  pIdxInfo->needToFreeIdxStr = 1;

  rc = SQLITE_OK;

done:
  if (idxStr) {
    sqlite3_str_finish(idxStr);
  }
  return rc;
}

// forward delcaration bc vec0Filter uses it
static int vec0Next(sqlite3_vtab_cursor *cur);

void merge_sorted_lists(f32 *a, i64 *a_rowids, i64 a_length, f32 *b,
                        i64 *b_rowids, i32 *b_top_idxs, i64 b_length, f32 *out,
                        i64 *out_rowids, i64 out_length, i64 *out_used) {
  // assert((a_length >= out_length) || (b_length >= out_length));
  i64 ptrA = 0;
  i64 ptrB = 0;
  for (int i = 0; i < out_length; i++) {
    if ((ptrA >= a_length) && (ptrB >= b_length)) {
      *out_used = i;
      return;
    }
    if (ptrA >= a_length) {
      out[i] = b[b_top_idxs[ptrB]];
      out_rowids[i] = b_rowids[b_top_idxs[ptrB]];
      ptrB++;
    } else if (ptrB >= b_length) {
      out[i] = a[ptrA];
      out_rowids[i] = a_rowids[ptrA];
      ptrA++;
    } else {
      // A NaN ranks after every number, as in min_idx()
      if (a[ptrA] <= b[b_top_idxs[ptrB]] || isnan(b[b_top_idxs[ptrB]])) {
        out[i] = a[ptrA];
        out_rowids[i] = a_rowids[ptrA];
        ptrA++;
      } else {
        out[i] = b[b_top_idxs[ptrB]];
        out_rowids[i] = b_rowids[b_top_idxs[ptrB]];
        ptrB++;
      }
    }
  }

  *out_used = out_length;
}

u8 *bitmap_new(i32 n) {
  assert(n % 8 == 0);
  u8 *p = sqlite3_malloc(n * sizeof(u8) / CHAR_BIT);
  if (p) {
    memset(p, 0, n * sizeof(u8) / CHAR_BIT);
  }
  return p;
}
u8 *bitmap_new_from(i32 n, u8 *from) {
  assert(n % 8 == 0);
  u8 *p = sqlite3_malloc(n * sizeof(u8) / CHAR_BIT);
  if (p) {
    memcpy(p, from, n / CHAR_BIT);
  }
  return p;
}

void bitmap_copy(u8 *base, u8 *from, i32 n) {
  assert(n % 8 == 0);
  memcpy(base, from, n / CHAR_BIT);
}

void bitmap_and_inplace(u8 *base, u8 *other, i32 n) {
  assert((n % 8) == 0);
  for (int i = 0; i < n / CHAR_BIT; i++) {
    base[i] = base[i] & other[i];
  }
}

void bitmap_set(u8 *bitmap, i32 position, int value) {
  if (value) {
    bitmap[position / CHAR_BIT] |= 1 << (position % CHAR_BIT);
  } else {
    bitmap[position / CHAR_BIT] &= ~(1 << (position % CHAR_BIT));
  }
}

int bitmap_get(u8 *bitmap, i32 position) {
  return (((bitmap[position / CHAR_BIT]) >> (position % CHAR_BIT)) & 1);
}

void bitmap_clear(u8 *bitmap, i32 n) {
  assert((n % 8) == 0);
  memset(bitmap, 0, n / CHAR_BIT);
}

void bitmap_fill(u8 *bitmap, i32 n) {
  assert((n % 8) == 0);
  memset(bitmap, 0xFF, n / CHAR_BIT);
}

int bitmap_any(u8 *bitmap, i32 n) {
  assert((n % 8) == 0);
  for (int i = 0; i < n / CHAR_BIT; i++) {
    if (bitmap[i]) {
      return 1;
    }
  }
  return 0;
}

/**
 * @brief Whether the candidate at index a ranks after the one at index b in
 * min_idx()'s order: by distance, a NaN distance after every number, and
 * between equal distances the smaller index after the larger.
 */
static int min_idx_after(const f32 *distances, i32 a, i32 b) {
  int a_nan = isnan(distances[a]), b_nan = isnan(distances[b]);
  if (a_nan != b_nan) {
    return a_nan;
  }
  if (!a_nan && distances[a] != distances[b]) {
    return distances[a] > distances[b];
  }
  return a < b;
}

/**
 * @brief Finds the k candidates with the smallest distances, and writes their
 * indices to out, nearest first.
 *
 * out holds a heap of the k candidates kept so far, whose root is the one that
 * ranks last, so n candidates cost n log k comparisons; the heap is then
 * sorted in place. This is upstream's SQLITE_VEC_EXPERIMENTAL_MIN_IDX variant
 * (https://github.com/asg017/sqlite-vec/blob/04d28bd21773981e2d266bbf6aa4efbd011eb4f6/sqlite-vec.c#L6516)
 * with min_idx_after() as its order, so that equal distances keep the larger
 * index first and a NaN distance ranks after every number.
 *
 * @param distances input f32 array of size n, the items to consider.
 * @param n: size of distances array.
 * @param candidates: bitmap of size n, the indices that may be chosen.
 * @param out: Output array of size k, will contain at most k element indicies
 * @param k: Size of output array
 * @param k_used: set to the number of indices written to out
 * @return int
 */
int min_idx(const f32 *distances, i32 n, u8 *candidates, i32 *out, i32 k,
            i32 *k_used) {
  assert(k > 0);
  assert(k <= n);

  int heap_size = 0;

#define HEAP_SIFT_UP(pos)                                                      \
  do {                                                                         \
    int _c = (pos);                                                            \
    while (_c > 0) {                                                           \
      int _p = (_c - 1) / 2;                                                   \
      if (min_idx_after(distances, out[_c], out[_p])) {                        \
        i32 _tmp = out[_p];                                                    \
        out[_p] = out[_c];                                                     \
        out[_c] = _tmp;                                                        \
        _c = _p;                                                               \
      } else                                                                   \
        break;                                                                 \
    }                                                                          \
  } while (0)

#define HEAP_SIFT_DOWN(pos, sz)                                                \
  do {                                                                         \
    int _p = (pos);                                                            \
    for (;;) {                                                                 \
      int _l = 2 * _p + 1, _r = 2 * _p + 2, _largest = _p;                     \
      if (_l < (sz) && min_idx_after(distances, out[_l], out[_largest]))       \
        _largest = _l;                                                         \
      if (_r < (sz) && min_idx_after(distances, out[_r], out[_largest]))       \
        _largest = _r;                                                         \
      if (_largest == _p)                                                      \
        break;                                                                 \
      i32 _tmp = out[_p];                                                      \
      out[_p] = out[_largest];                                                 \
      out[_largest] = _tmp;                                                    \
      _p = _largest;                                                           \
    }                                                                          \
  } while (0)

  for (int i = 0; i < n; i++) {
    if (!bitmap_get(candidates, i))
      continue;
    if (heap_size < k) {
      out[heap_size] = i;
      heap_size++;
      HEAP_SIFT_UP(heap_size - 1);
    } else if (min_idx_after(distances, out[0], i)) {
      out[0] = i;
      HEAP_SIFT_DOWN(0, heap_size);
    }
  }

  // Heapsort to produce ascending order.
  for (int i = heap_size - 1; i > 0; i--) {
    i32 tmp = out[0];
    out[0] = out[i];
    out[i] = tmp;
    HEAP_SIFT_DOWN(0, i);
  }

#undef HEAP_SIFT_UP
#undef HEAP_SIFT_DOWN

  *k_used = heap_size;
  return SQLITE_OK;
}

int vec0_get_metadata_text_long_value(vec0_vtab *p, sqlite3_stmt **stmt,
                                      int metadata_idx, i64 rowid, int *n,
                                      char **s) {
  int rc;
  if (!(*stmt)) {
    const char *zSql =
        sqlite3_mprintf("select data from " VEC0_SHADOW_METADATA_TEXT_DATA_NAME
                        " where rowid = ?",
                        p->schemaName, p->tableName, metadata_idx);
    if (!zSql) {
      rc = SQLITE_NOMEM;
      goto done;
    }
    rc = sqlite3_prepare_v2(p->db, zSql, -1, stmt, NULL);
    sqlite3_free((void *)zSql);
    if (rc != SQLITE_OK) {
      goto done;
    }
  }

  sqlite3_reset(*stmt);
  sqlite3_bind_int64(*stmt, 1, rowid);
  rc = sqlite3_step(*stmt);
  if (rc != SQLITE_ROW) {
    rc = vec0_error_rc(rc);
    goto done;
  }
  *s = (char *)sqlite3_column_text(*stmt, 0);
  *n = sqlite3_column_bytes(*stmt, 0);
  rc = SQLITE_OK;
done:
  return rc;
}

/**
 * @brief Crete at "iterator" (sqlite3_stmt) of chunks with the given
 * constraints
 *
 * Any VEC0_IDXSTR_KIND_KNN_PARTITON_CONSTRAINT values in idxStr/argv will be
 * applied as WHERE constraints in the underlying stmt SQL, and any consumer of
 * the stmt can freely step through the stmt with all constraints satisfied.
 *
 * @param p - vec0_vtab
 * @param idxStr - the xBestIndex/xFilter idxstr containing VEC0_IDXSTR values
 * @param argc - number of argv values from xFilter
 * @param argv - array of sqlite3_value from xFilter
 * @param outStmt - output sqlite3_stmt of chunks with all filters applied
 * @return int SQLITE_OK on success, error code otherwise
 */
int vec0_chunks_iter(vec0_vtab *p, const char *idxStr, int argc,
                     sqlite3_value **argv, sqlite3_stmt **outStmt) {
  // always null terminated, enforced by SQLite
  int idxStrLength = strlen(idxStr);
  // "1" refers to the initial vec0_query_plan char, 4 is the number of chars
  // per "element"
  int numValueEntries = (idxStrLength - 1) / 4;
  assert(argc == numValueEntries);

  int rc;
  sqlite3_str *s = sqlite3_str_new(NULL);
  sqlite3_str_appendf(s,
                      "select chunk_id, validity, rowids "
                      " from " VEC0_SHADOW_CHUNKS_NAME,
                      p->schemaName, p->tableName);

  int appendedWhere = 0;
  for (int i = 0; i < numValueEntries; i++) {
    int idx = 1 + (i * 4);
    char kind = idxStr[idx + 0];
    if (kind != VEC0_IDXSTR_KIND_KNN_PARTITON_CONSTRAINT) {
      continue;
    }

    int partition_idx = idxStr[idx + 1] - 'A';
    int operator = idxStr[idx + 2];
    char collation = idxStr[idx + 3];

    if (!appendedWhere) {
      sqlite3_str_appendall(s, " WHERE ");
      appendedWhere = 1;
    } else {
      sqlite3_str_appendall(s, " AND ");
    }
    switch (operator) {
    case VEC0_PARTITION_OPERATOR_EQ:
      sqlite3_str_appendf(s, " partition%02d = ? ", partition_idx);
      break;
    case VEC0_PARTITION_OPERATOR_GT:
      sqlite3_str_appendf(s, " partition%02d > ? ", partition_idx);
      break;
    case VEC0_PARTITION_OPERATOR_LE:
      sqlite3_str_appendf(s, " partition%02d <= ? ", partition_idx);
      break;
    case VEC0_PARTITION_OPERATOR_LT:
      sqlite3_str_appendf(s, " partition%02d < ? ", partition_idx);
      break;
    case VEC0_PARTITION_OPERATOR_GE:
      sqlite3_str_appendf(s, " partition%02d >= ? ", partition_idx);
      break;
    case VEC0_PARTITION_OPERATOR_NE:
      sqlite3_str_appendf(s, " partition%02d != ? ", partition_idx);
      break;
#if COMPILER_SUPPORTS_VTAB_IN
    case VEC0_PARTITION_OPERATOR_IN: {
      // one parameter per value, bound below
      sqlite3_str_appendf(s, " partition%02d IN (", partition_idx);
      sqlite3_value *item;
      int nItems = 0;
      for (rc = sqlite3_vtab_in_first(argv[i], &item); rc == SQLITE_OK && item;
           rc = sqlite3_vtab_in_next(argv[i], &item)) {
        sqlite3_str_appendall(s, nItems++ ? ", ?" : "?");
      }
      if (rc != SQLITE_DONE) {
        sqlite3_free(sqlite3_str_finish(s));
        return rc;
      }
      sqlite3_str_appendall(s, ") ");
      break;
    }
#endif
    case VEC0_PARTITION_OPERATOR_LIKE:
      sqlite3_str_appendf(s, " partition%02d LIKE ? ", partition_idx);
      break;
    case VEC0_PARTITION_OPERATOR_GLOB:
      sqlite3_str_appendf(s, " partition%02d GLOB ? ", partition_idx);
      break;
    case VEC0_PARTITION_OPERATOR_IS:
      sqlite3_str_appendf(s, " partition%02d IS ? ", partition_idx);
      break;
    case VEC0_PARTITION_OPERATOR_ISNOT:
      sqlite3_str_appendf(s, " partition%02d IS NOT ? ", partition_idx);
      break;
    case VEC0_PARTITION_OPERATOR_ISNULL:
      sqlite3_str_appendf(s, " partition%02d IS NULL ", partition_idx);
      break;
    case VEC0_PARTITION_OPERATOR_ISNOTNULL:
      sqlite3_str_appendf(s, " partition%02d IS NOT NULL ", partition_idx);
      break;
    default: {
      char *zSql = sqlite3_str_finish(s);
      sqlite3_free(zSql);
      return SQLITE_ERROR;
    }
    }
    if (collation == VEC0_METADATA_COLLATION_NOCASE) {
      sqlite3_str_appendall(s, "COLLATE NOCASE ");
    } else if (collation == VEC0_METADATA_COLLATION_RTRIM) {
      sqlite3_str_appendall(s, "COLLATE RTRIM ");
    }
  }

  char *zSql = sqlite3_str_finish(s);
  if (!zSql) {
    return SQLITE_NOMEM;
  }

  rc = sqlite3_prepare_v2(p->db, zSql, -1, outStmt, NULL);
  sqlite3_free(zSql);
  if (rc != SQLITE_OK) {
    return rc;
  }

  int n = 1;
  for (int i = 0; i < numValueEntries; i++) {
    int idx = 1 + (i * 4);
    char kind = idxStr[idx + 0];
    if (kind != VEC0_IDXSTR_KIND_KNN_PARTITON_CONSTRAINT) {
      continue;
    }
    switch (idxStr[idx + 2]) {
#if COMPILER_SUPPORTS_VTAB_IN
    case VEC0_PARTITION_OPERATOR_IN: {
      sqlite3_value *item;
      for (rc = sqlite3_vtab_in_first(argv[i], &item); rc == SQLITE_OK && item;
           rc = sqlite3_vtab_in_next(argv[i], &item)) {
        sqlite3_bind_value(*outStmt, n++, item);
      }
      if (rc != SQLITE_DONE) {
        return rc;
      }
      rc = SQLITE_OK;
      break;
    }
#endif
    case VEC0_PARTITION_OPERATOR_ISNULL:
    case VEC0_PARTITION_OPERATOR_ISNOTNULL:
      break;
    default:
      sqlite3_bind_value(*outStmt, n++, argv[i]);
    }
  }

  return rc;
}

// a single `xxx in (...)` constraint on a metadata column. TEXT or INTEGER only
// for now.
struct Vec0MetadataIn {
  // index of argv[i]` the constraint is on
  int argv_idx;
  // metadata column index of the constraint, derived from idxStr + argv_idx
  int metadata_idx;
  // array of the copied `(...)` values from
  // sqlite3_vtab_in_first()/sqlite3_vtab_in_next()
  struct Array array;
};

// Array elements for `xxx in (...)` values for a text column. basically just a
// string
struct Vec0MetadataInTextEntry {
  int n;
  char *zString;
};

// Frees all zString pointers in a Vec0MetadataInTextEntry array and cleans up
// the array.
static void vec0_metadata_in_text_cleanup(struct Array *arr) {
  for (size_t j = 0; j < arr->length; j++) {
    struct Vec0MetadataInTextEntry *e =
        &((struct Vec0MetadataInTextEntry *)arr->z)[j];
    sqlite3_free(e->zString);
  }
  array_cleanup(arr);
}

// Helper function to detect if a LIKE pattern is prefix-only (e.g., 'abc%')
// Returns 1 if the pattern ends with '%' and has no wildcards in the middle
// Returns 0 otherwise
static int vec0_is_prefix_only_like_pattern(const char *pattern, int n) {
  if (n == 0)
    return 0;

  // Must end with '%'
  if (pattern[n - 1] != '%')
    return 0;

  // Check for wildcards in the prefix (before the trailing '%')
  for (int i = 0; i < n - 1; i++) {
    if (pattern[i] == '%' || pattern[i] == '_') {
      return 0;
    }
  }

  return 1;
}

static int vec0_is_prefix_only_glob_pattern(const char *pattern, int n) {
  if (n == 0)
    return 0;

  // Must end with '*'
  if (pattern[n - 1] != '*')
    return 0;

  // Check for wildcards and character classes in the prefix (before the
  // trailing '*')
  for (int i = 0; i < n - 1; i++) {
    if (pattern[i] == '*' || pattern[i] == '?' || pattern[i] == '[') {
      return 0;
    }
  }

  return 1;
}

// A KNN query's filters compare a constraint's value with a row's value by
// SQLite's rules
// (https://www.sqlite.org/datatype3.html#comparison_expressions). vec0 declares
// its metadata columns and `distance` without a type, so SQLite converts
// neither value when it compares one with a bound parameter or a literal: NULL
// compares with nothing, INTEGER and REAL values compare numerically, every
// number is less than any TEXT, and every TEXT is less than any BLOB. A filter
// sees only the value, not the expression that produced it, so it compares
// every value this way. SQLite itself converts a column's TEXT to a number when
// the other side has numeric affinity, so a TEXT '5' equals CAST(5 AS INTEGER)
// in a plain scan but not in a KNN query's filter.
// A `distance` filter still rounds a numeric value to float before comparing.
// vec0 declares its `rowid` column, or an integer primary key column, INTEGER,
// so SQLite applies numeric affinity to a value it compares with that column,
// as with an ordinary table's rowid. vec0's own rowid lookups (`rowid = ?`, and
// a KNN query's `rowid in (...)`) do the same, as SQLite does for an INTEGER
// PRIMARY KEY, so '5' finds rowid 5 either way.

// Whether a comparison holds, given the sign of a row's value compared with
// the constraint's value.
static int vec0_metadata_operator_holds(vec0_metadata_operator op, int cmp) {
  switch (op) {
  case VEC0_METADATA_OPERATOR_EQ:
  case VEC0_METADATA_OPERATOR_IS:
    return cmp == 0;
  case VEC0_METADATA_OPERATOR_NE:
  case VEC0_METADATA_OPERATOR_ISNOT:
    return cmp != 0;
  case VEC0_METADATA_OPERATOR_LT:
    return cmp < 0;
  case VEC0_METADATA_OPERATOR_LE:
    return cmp <= 0;
  case VEC0_METADATA_OPERATOR_GT:
    return cmp > 0;
  case VEC0_METADATA_OPERATOR_GE:
    return cmp >= 0;
  default:
    return 0;
  }
}

// Compares an integer with a real exactly: negative, zero or positive as i is
// less than, equal to or greater than r. This is SQLite's
// sqlite3IntFloatCompare() (src/vdbeaux.c) without its NaN check; no NaN
// reaches it, since SQLite stores a NaN as NULL.
static int vec0_compare_i64_double(i64 i, double r) {
  if (r < -9223372036854775808.0)
    return 1;
  if (r >= 9223372036854775808.0)
    return -1;
  i64 y = (i64)r;
  if (i < y)
    return -1;
  if (i > y)
    return 1;
  double s = (double)i;
  return (s < r) ? -1 : (s > r);
}

// The integer a value equals: an INTEGER, or a REAL without a fraction inside
// i64's range. Returns 0 for any other value, which equals no integer.
static int vec0_value_as_i64(sqlite3_value *value, i64 *out) {
  switch (sqlite3_value_type(value)) {
  case SQLITE_INTEGER:
    *out = sqlite3_value_int64(value);
    return 1;
  case SQLITE_FLOAT: {
    double r = sqlite3_value_double(value);
    if (r < -9223372036854775808.0 || r >= 9223372036854775808.0)
      return 0;
    i64 y = (i64)r;
    if (vec0_compare_i64_double(y, r) != 0)
      return 0;
    *out = y;
    return 1;
  }
  default:
    return 0;
  }
}

// The rowid a value equals after numeric affinity, as SQLite applies it to a
// value compared with an INTEGER PRIMARY KEY. Returns 0 when it equals no
// rowid. Like sqlite3VdbeIntegerAffinity(), it reads no REAL as -2^63.
static int vec0_value_as_rowid(sqlite3_value *value, i64 *rowid) {
  sqlite3_value_numeric_type(value);
  return vec0_value_as_i64(value, rowid) &&
         (sqlite3_value_type(value) == SQLITE_INTEGER || *rowid != INT64_MIN);
}

// The result a metadata constraint gives every row when its value decides it
// alone, or -1 when each row's value must be compared with it.
static int vec0_metadata_constant_result(vec0_metadata_column_kind kind,
                                         vec0_metadata_operator op,
                                         sqlite3_value *value) {
  if (op == VEC0_METADATA_OPERATOR_IN || op == VEC0_METADATA_OPERATOR_ISNULL ||
      op == VEC0_METADATA_OPERATOR_ISNOTNULL) {
    return -1;
  }
  int type = sqlite3_value_type(value);
  if (type == SQLITE_NULL) {
    // no metadata value is NULL, so only IS NOT holds against one
    return op == VEC0_METADATA_OPERATOR_ISNOT;
  }
  if (op == VEC0_METADATA_OPERATOR_LIKE || op == VEC0_METADATA_OPERATOR_GLOB) {
    // LIKE and GLOB read any pattern as text
    return -1;
  }
  if (kind == VEC0_METADATA_COLUMN_KIND_TEXT) {
    if (type == SQLITE_TEXT)
      return -1;
    return vec0_metadata_operator_holds(op, type == SQLITE_BLOB ? -1 : 1);
  }
  if (type == SQLITE_TEXT || type == SQLITE_BLOB) {
    return vec0_metadata_operator_holds(op, -1);
  }
  if (kind == VEC0_METADATA_COLUMN_KIND_BOOLEAN) {
    // a boolean is the integer 0 or 1, and takes only (in)equality operators
    i64 v;
    if (vec0_value_as_i64(value, &v) && (v == 0 || v == 1))
      return -1;
    return vec0_metadata_operator_holds(op, 1);
  }
  return -1;
}

// Compares text the way SQLite's BINARY collation does: memcmp() over the
// shorter length, then the shorter value sorts first.
static int vec0_text_binary_cmp(const char *a, int na, const char *b, int nb) {
  int cmp = memcmp(a, b, min(na, nb));
  if (cmp != 0) {
    return cmp;
  }
  return (na > nb) - (na < nb);
}

// The UTF-8 conversion below is SQLite's own, from READ_UTF8, WRITE_UTF16LE,
// WRITE_UTF16BE and sqlite3Utf8Trans1[] in
// https://sqlite.org/src/file/src/utf.c, so a value converts to the bytes
// SQLite stores for it in a UTF-16 database.
static const unsigned char vec0Utf8Trans1[] = {
    0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0a,
    0x0b, 0x0c, 0x0d, 0x0e, 0x0f, 0x10, 0x11, 0x12, 0x13, 0x14, 0x15,
    0x16, 0x17, 0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f, 0x00,
    0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0a, 0x0b,
    0x0c, 0x0d, 0x0e, 0x0f, 0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06,
    0x07, 0x00, 0x01, 0x02, 0x03, 0x00, 0x01, 0x00, 0x00,
};

// Reads one character of UTF-8, reading an overlong form, a surrogate, U+FFFE
// or U+FFFF as U+FFFD.
static u32 vec0_utf8_read(const unsigned char **pz, const unsigned char *zEnd) {
  u32 c = *((*pz)++);
  if (c >= 0xc0) {
    c = vec0Utf8Trans1[c - 0xc0];
    while (*pz != zEnd && (**pz & 0xc0) == 0x80) {
      c = (c << 6) + (0x3f & *((*pz)++));
    }
    if (c < 0x80 || (c & 0xFFFFF800) == 0xD800 || (c & 0xFFFFFFFE) == 0xFFFE) {
      c = 0xFFFD;
    }
  }
  return c;
}

// Writes c as UTF-16 in the byte order of encoding, SQLITE_UTF16LE or
// SQLITE_UTF16BE, and returns the number of bytes, 2 or 4.
static int vec0_utf16_write(unsigned char *z, u32 c, int encoding) {
  // the offsets of the high and low byte within each 16-bit unit
  int hi = encoding == SQLITE_UTF16BE ? 0 : 1;
  int lo = 1 - hi;
  if (c <= 0xFFFF) {
    z[hi] = (unsigned char)((c >> 8) & 0x00FF);
    z[lo] = (unsigned char)(c & 0x00FF);
    return 2;
  }
  z[hi] = (unsigned char)(0x00D8 + (((c - 0x10000) >> 18) & 0x03));
  z[lo] =
      (unsigned char)(((c >> 10) & 0x003F) + (((c - 0x10000) >> 10) & 0x00C0));
  z[2 + hi] = (unsigned char)(0x00DC + ((c >> 8) & 0x03));
  z[2 + lo] = (unsigned char)(c & 0x00FF);
  return 4;
}

// Compares UTF-8 text the way SQLite's BINARY collation compares it in a
// database whose encoding is SQLITE_UTF16LE or SQLITE_UTF16BE: memcmp() over
// the bytes of each value's UTF-16 form, then the shorter value sorts first.
static int vec0_text_utf16_cmp(int encoding, const char *a, int na,
                               const char *b, int nb) {
  const unsigned char *za = (const unsigned char *)a;
  const unsigned char *zb = (const unsigned char *)b;
  const unsigned char *zaEnd = za + na;
  const unsigned char *zbEnd = zb + nb;
  unsigned char ua[4], ub[4];
  int ia = 0, nua = 0, ib = 0, nub = 0;
  for (;;) {
    if (ia == nua && za != zaEnd) {
      nua = vec0_utf16_write(ua, vec0_utf8_read(&za, zaEnd), encoding);
      ia = 0;
    }
    if (ib == nub && zb != zbEnd) {
      nub = vec0_utf16_write(ub, vec0_utf8_read(&zb, zbEnd), encoding);
      ib = 0;
    }
    int aDone = ia == nua;
    int bDone = ib == nub;
    if (aDone || bDone) {
      return bDone - aDone;
    }
    if (ua[ia] != ub[ib]) {
      return ua[ia] - ub[ib];
    }
    ia++;
    ib++;
  }
}

// Compares text the way SQLite's BINARY, NOCASE, or RTRIM collation does in a
// database of the given text encoding. NOCASE folds ASCII letters only, and
// sqlite3_strnicmp() stops at a NUL both values have at the same offset. RTRIM
// ignores trailing spaces, but no other trailing whitespace. SQLite registers
// BINARY in each encoding and NOCASE and RTRIM for UTF-8 only, so those two
// compare UTF-8 in every encoding (openDatabase() in
// https://sqlite.org/src/file/src/main.c).
static int vec0_text_cmp(vec0_metadata_collation collation, int encoding,
                         const char *a, int na, const char *b, int nb) {
  switch (collation) {
  case VEC0_METADATA_COLLATION_NOCASE: {
    int cmp = sqlite3_strnicmp(a, b, min(na, nb));
    if (cmp != 0) {
      return cmp;
    }
    return (na > nb) - (na < nb);
  }
  case VEC0_METADATA_COLLATION_RTRIM:
    while (na > 0 && a[na - 1] == ' ')
      na--;
    while (nb > 0 && b[nb - 1] == ' ')
      nb--;
    break;
  case VEC0_METADATA_COLLATION_BINARY:
    if (encoding != SQLITE_UTF8) {
      return vec0_text_utf16_cmp(encoding, a, na, b, nb);
    }
    break;
  }
  return vec0_text_binary_cmp(a, na, b, nb);
}

// Compares the first n bytes of two values that have the same length, the way
// BINARY or NOCASE does. Values equal under either have the same length, so
// the EQ and IN filters compare only values of the target's length.
static int vec0_text_same_length_cmp(vec0_metadata_collation collation,
                                     const char *a, const char *b, int n) {
  if (collation == VEC0_METADATA_COLLATION_NOCASE) {
    return sqlite3_strnicmp(a, b, n);
  }
  return memcmp(a, b, n);
}

// Sets bit i of b when op holds between the whole text value of row i and any
// of the targets, compared with the collation. A value longer than the view's
// 12 bytes is read from the long-text table.
static int vec0_metadata_filter_text_whole(
    vec0_vtab *p, sqlite3_stmt **stmt, int metadata_idx, const void *buffer,
    const i64 *rowids, int size, vec0_metadata_operator op,
    vec0_metadata_collation collation,
    const struct Vec0MetadataInTextEntry *targets, size_t nTargets, u8 *b) {
  for (int i = 0; i < size; i++) {
    u8 *view = &((u8 *)buffer)[i * VEC0_METADATA_TEXT_VIEW_BUFFER_LENGTH];
    int n = ((int *)view)[0];
    char *s = (char *)&view[4];
    if (n > VEC0_METADATA_TEXT_VIEW_DATA_LENGTH) {
      int nFull;
      int rc = vec0_get_metadata_text_long_value(p, stmt, metadata_idx,
                                                 rowids[i], &nFull, &s);
      if (rc != SQLITE_OK) {
        return rc;
      }
      if (n != nFull) {
        return SQLITE_ERROR;
      }
    }
    for (size_t j = 0; j < nTargets; j++) {
      int cmp = vec0_text_cmp(collation, p->textEncoding, s, n,
                              targets[j].zString, targets[j].n);
      if (vec0_metadata_operator_holds(op, cmp)) {
        bitmap_set(b, i, 1);
        break;
      }
    }
  }
  return SQLITE_OK;
}

int vec0_metadata_filter_text(vec0_vtab *p, sqlite3_value *value,
                              const void *buffer, int size,
                              vec0_metadata_operator op,
                              vec0_metadata_collation collation, u8 *b,
                              int metadata_idx, int chunk_rowid,
                              struct Array *aMetadataIn, int argv_idx) {
  int rc;
  sqlite3_stmt *stmt = NULL;
  i64 *rowids = NULL;
  sqlite3_blob *rowidsBlob;
  const char *sTarget = (const char *)sqlite3_value_text(value);
  int nTarget = sqlite3_value_bytes(value);
  struct Vec0MetadataInTextEntry target = {nTarget, (char *)sTarget};

  // TODO(perf): only text metadata news the rowids BLOB. Make it so that
  // rowids BLOB is re-used when multiple fitlers on text columns,
  // ex "name BETWEEN 'a' and 'b'""
  rc = sqlite3_blob_open(p->db, p->schemaName, p->shadowChunksName, "rowids",
                         chunk_rowid, 0, &rowidsBlob);
  if (rc != SQLITE_OK) {
    return rc;
  }
  assert(sqlite3_blob_bytes(rowidsBlob) % sizeof(i64) == 0);
  assert((size_t)(sqlite3_blob_bytes(rowidsBlob) / sizeof(i64)) ==
         (size_t)size);

  rowids = sqlite3_malloc(sqlite3_blob_bytes(rowidsBlob));
  if (!rowids) {
    sqlite3_blob_close(rowidsBlob);
    return SQLITE_NOMEM;
  }

  rc = sqlite3_blob_read(rowidsBlob, rowids, sqlite3_blob_bytes(rowidsBlob), 0);
  if (rc != SQLITE_OK) {
    sqlite3_blob_close(rowidsBlob);
    sqlite3_free(rowids);
    return rc;
  }
  sqlite3_blob_close(rowidsBlob);

  // Map IS/ISNOT to EQ/NE (they behave identically for text)
  if (op == VEC0_METADATA_OPERATOR_IS) {
    op = VEC0_METADATA_OPERATOR_EQ;
  } else if (op == VEC0_METADATA_OPERATOR_ISNOT) {
    op = VEC0_METADATA_OPERATOR_NE;
  }

  switch (op) {
    int nPrefix;
    char *sPrefix;
    char *sFull;
    int nFull;
    u8 *view;
  case VEC0_METADATA_OPERATOR_EQ: {
    if (collation == VEC0_METADATA_COLLATION_RTRIM) {
      // RTRIM ignores trailing spaces, so values of different lengths can be
      // equal and the length check below does not apply
      rc = vec0_metadata_filter_text_whole(p, &stmt, metadata_idx, buffer,
                                           rowids, size, op, collation, &target,
                                           1, b);
      if (rc != SQLITE_OK) {
        goto done;
      }
      break;
    }
    for (int i = 0; i < size; i++) {
      view = &((u8 *)buffer)[i * VEC0_METADATA_TEXT_VIEW_BUFFER_LENGTH];
      nPrefix = ((int *)view)[0];
      sPrefix = (char *)&view[4];

      // for EQ the text lengths must match
      if (nPrefix != nTarget) {
        bitmap_set(b, i, 0);
        continue;
      }
      int cmpPrefix = vec0_text_same_length_cmp(
          collation, sPrefix, sTarget,
          min(nPrefix, VEC0_METADATA_TEXT_VIEW_DATA_LENGTH));

      // for short strings, use the prefix comparison direclty
      if (nPrefix <= VEC0_METADATA_TEXT_VIEW_DATA_LENGTH) {
        bitmap_set(b, i, cmpPrefix == 0);
        continue;
      }
      // for EQ on longs strings, the prefix must match
      if (cmpPrefix) {
        bitmap_set(b, i, 0);
        continue;
      }
      // consult the full string
      rc = vec0_get_metadata_text_long_value(p, &stmt, metadata_idx, rowids[i],
                                             &nFull, &sFull);
      if (rc != SQLITE_OK) {
        goto done;
      }
      if (nPrefix != nFull) {
        rc = SQLITE_ERROR;
        goto done;
      }
      bitmap_set(b, i,
                 vec0_text_same_length_cmp(collation, sFull, sTarget, nFull) ==
                     0);
    }
    break;
  }
  case VEC0_METADATA_OPERATOR_NE: {
    for (int i = 0; i < size; i++) {
      view = &((u8 *)buffer)[i * VEC0_METADATA_TEXT_VIEW_BUFFER_LENGTH];
      nPrefix = ((int *)view)[0];
      sPrefix = (char *)&view[4];

      // for NE if text lengths dont match, it never will
      if (nPrefix != nTarget) {
        bitmap_set(b, i, 1);
        continue;
      }

      int cmpPrefix = memcmp(sPrefix, sTarget,
                             min(nPrefix, VEC0_METADATA_TEXT_VIEW_DATA_LENGTH));

      // for short strings, use the prefix comparison direclty
      if (nPrefix <= VEC0_METADATA_TEXT_VIEW_DATA_LENGTH) {
        bitmap_set(b, i, cmpPrefix != 0);
        continue;
      }
      // for NE on longs strings, if prefixes dont match, then long string wont
      if (cmpPrefix) {
        bitmap_set(b, i, 1);
        continue;
      }
      // consult the full string
      rc = vec0_get_metadata_text_long_value(p, &stmt, metadata_idx, rowids[i],
                                             &nFull, &sFull);
      if (rc != SQLITE_OK) {
        goto done;
      }
      if (nPrefix != nFull) {
        rc = SQLITE_ERROR;
        goto done;
      }
      bitmap_set(b, i, memcmp(sFull, sTarget, nFull) != 0);
    }
    break;
  }
  case VEC0_METADATA_OPERATOR_GT:
  case VEC0_METADATA_OPERATOR_GE:
  case VEC0_METADATA_OPERATOR_LE:
  case VEC0_METADATA_OPERATOR_LT: {
    // TODO(perf): may not need to compare full text in some cases
    rc = vec0_metadata_filter_text_whole(p, &stmt, metadata_idx, buffer, rowids,
                                         size, op, collation, &target, 1, b);
    if (rc != SQLITE_OK) {
      goto done;
    }
    break;
  }

  case VEC0_METADATA_OPERATOR_IN: {
    int metadataInIdx = -1;
    for (size_t i = 0; i < aMetadataIn->length; i++) {
      struct Vec0MetadataIn *metadataIn =
          &(((struct Vec0MetadataIn *)aMetadataIn->z)[i]);
      if (metadataIn->argv_idx == argv_idx) {
        metadataInIdx = i;
        break;
      }
    }
    if (metadataInIdx < 0) {
      rc = SQLITE_ERROR;
      goto done;
    }

    struct Vec0MetadataIn *metadataIn =
        &((struct Vec0MetadataIn *)aMetadataIn->z)[metadataInIdx];
    struct Array *aTarget = &(metadataIn->array);

    if (collation == VEC0_METADATA_COLLATION_RTRIM) {
      // RTRIM ignores trailing spaces, so values of different lengths can be
      // equal and the length check below does not apply
      rc = vec0_metadata_filter_text_whole(
          p, &stmt, metadata_idx, buffer, rowids, size,
          VEC0_METADATA_OPERATOR_EQ, collation, aTarget->z, aTarget->length, b);
      if (rc != SQLITE_OK) {
        goto done;
      }
      break;
    }

    int nPrefix;
    char *sPrefix;
    char *sFull;
    int nFull;
    u8 *view;
    for (int i = 0; i < size; i++) {
      view = &((u8 *)buffer)[i * VEC0_METADATA_TEXT_VIEW_BUFFER_LENGTH];
      nPrefix = ((int *)view)[0];
      sPrefix = (char *)&view[4];
      for (size_t target_idx = 0; target_idx < aTarget->length; target_idx++) {
        struct Vec0MetadataInTextEntry *entry =
            &(((struct Vec0MetadataInTextEntry *)aTarget->z)[target_idx]);
        if (entry->n != nPrefix) {
          continue;
        }
        int cmpPrefix = vec0_text_same_length_cmp(
            collation, sPrefix, entry->zString,
            min(nPrefix, VEC0_METADATA_TEXT_VIEW_DATA_LENGTH));
        if (nPrefix <= VEC0_METADATA_TEXT_VIEW_DATA_LENGTH) {
          if (cmpPrefix == 0) {
            bitmap_set(b, i, 1);
            break;
          }
          continue;
        }
        if (cmpPrefix) {
          continue;
        }

        rc = vec0_get_metadata_text_long_value(p, &stmt, metadata_idx,
                                               rowids[i], &nFull, &sFull);
        if (rc != SQLITE_OK) {
          goto done;
        }
        if (nPrefix != nFull) {
          rc = SQLITE_ERROR;
          goto done;
        }
        if (vec0_text_same_length_cmp(collation, sFull, entry->zString,
                                      nFull) == 0) {
          bitmap_set(b, i, 1);
          break;
        }
      }
    }
    break;
  }

  case VEC0_METADATA_OPERATOR_LIKE: {
    // SQLite reads a pattern only up to a NUL
    nTarget = (int)strlen(sTarget);
    int is_prefix_only = vec0_is_prefix_only_like_pattern(sTarget, nTarget);

    if (is_prefix_only) {
      // Fast path: prefix-only pattern (e.g., 'abc%')
      // Can use the 12-byte cache for optimization
      int nPattern = nTarget - 1; // Exclude trailing '%'

      for (int i = 0; i < size; i++) {
        view = &((u8 *)buffer)[i * VEC0_METADATA_TEXT_VIEW_BUFFER_LENGTH];
        nPrefix = ((int *)view)[0];
        sPrefix = (char *)&view[4];

        // String must be at least as long as the pattern prefix
        if (nPrefix < nPattern) {
          bitmap_set(b, i, 0);
          continue;
        }

        // Compare pattern prefix against cached prefix (case-insensitive)
        int cmpLen = min(nPattern, VEC0_METADATA_TEXT_VIEW_DATA_LENGTH);
        int cmpPrefix = sqlite3_strnicmp(sPrefix, sTarget, cmpLen);

        // For short strings (fits in cache), prefix comparison is enough
        if (nPrefix <= VEC0_METADATA_TEXT_VIEW_DATA_LENGTH) {
          bitmap_set(b, i, cmpPrefix == 0);
          continue;
        }

        // For long strings, if cached prefix doesn't match, reject early
        if (cmpPrefix != 0) {
          bitmap_set(b, i, 0);
          continue;
        }

        // If pattern fits in cache, it matches
        if (nPattern <= VEC0_METADATA_TEXT_VIEW_DATA_LENGTH) {
          bitmap_set(b, i, 1);
          continue;
        }

        // Pattern is longer than cache, need to check full string
        rc = vec0_get_metadata_text_long_value(p, &stmt, metadata_idx,
                                               rowids[i], &nFull, &sFull);
        if (rc != SQLITE_OK) {
          goto done;
        }
        if (nPrefix != nFull) {
          rc = SQLITE_ERROR;
          goto done;
        }

        // Check if full string starts with pattern prefix (case-insensitive)
        bitmap_set(b, i, sqlite3_strnicmp(sFull, sTarget, nPattern) == 0);
      }
    } else {
      // Slow path: complex pattern (e.g., '%abc', 'a%b', etc.)
      // Must fetch and check full string for each row
      for (int i = 0; i < size; i++) {
        view = &((u8 *)buffer)[i * VEC0_METADATA_TEXT_VIEW_BUFFER_LENGTH];
        nPrefix = ((int *)view)[0];
        sPrefix = (char *)&view[4];

        // For short strings, use cached value directly
        if (nPrefix <= VEC0_METADATA_TEXT_VIEW_DATA_LENGTH) {
          // a 12-byte value fills the view without a NUL terminator
          char zPrefix[VEC0_METADATA_TEXT_VIEW_DATA_LENGTH + 1];
          memcpy(zPrefix, sPrefix, nPrefix);
          zPrefix[nPrefix] = '\0';
          // sqlite3_strlike returns 0 on match, non-zero otherwise
          bitmap_set(b, i, sqlite3_strlike(sTarget, zPrefix, 0) == 0);
          continue;
        }

        // For long strings, fetch full value
        rc = vec0_get_metadata_text_long_value(p, &stmt, metadata_idx,
                                               rowids[i], &nFull, &sFull);
        if (rc != SQLITE_OK) {
          goto done;
        }
        if (nPrefix != nFull) {
          rc = SQLITE_ERROR;
          goto done;
        }

        // Use SQLite's LIKE implementation
        bitmap_set(b, i, sqlite3_strlike(sTarget, sFull, 0) == 0);
      }
    }
    break;
  }

  case VEC0_METADATA_OPERATOR_GLOB: {
    // SQLite reads a pattern only up to a NUL
    nTarget = (int)strlen(sTarget);
    int is_prefix_only = vec0_is_prefix_only_glob_pattern(sTarget, nTarget);

    if (is_prefix_only) {
      // Fast path: prefix-only pattern (e.g., 'abc*')
      // Can use the 12-byte cache for optimization
      int nPattern = nTarget - 1; // Exclude trailing '*'

      for (int i = 0; i < size; i++) {
        view = &((u8 *)buffer)[i * VEC0_METADATA_TEXT_VIEW_BUFFER_LENGTH];
        nPrefix = ((int *)view)[0];
        sPrefix = (char *)&view[4];

        // String must be at least as long as the pattern prefix
        if (nPrefix < nPattern) {
          bitmap_set(b, i, 0);
          continue;
        }

        // Compare pattern prefix against cached prefix (case-sensitive for
        // GLOB)
        int cmpLen = min(nPattern, VEC0_METADATA_TEXT_VIEW_DATA_LENGTH);
        int cmpPrefix = strncmp(sPrefix, sTarget, cmpLen);

        // For short strings (fits in cache), prefix comparison is enough
        if (nPrefix <= VEC0_METADATA_TEXT_VIEW_DATA_LENGTH) {
          bitmap_set(b, i, cmpPrefix == 0);
          continue;
        }

        // For long strings, if cached prefix doesn't match, reject early
        if (cmpPrefix != 0) {
          bitmap_set(b, i, 0);
          continue;
        }

        // If pattern fits in cache, it matches
        if (nPattern <= VEC0_METADATA_TEXT_VIEW_DATA_LENGTH) {
          bitmap_set(b, i, 1);
          continue;
        }

        // Pattern is longer than cache, need to check full string
        rc = vec0_get_metadata_text_long_value(p, &stmt, metadata_idx,
                                               rowids[i], &nFull, &sFull);
        if (rc != SQLITE_OK) {
          goto done;
        }
        if (nPrefix != nFull) {
          rc = SQLITE_ERROR;
          goto done;
        }

        // Check if full string starts with pattern prefix (case-sensitive)
        bitmap_set(b, i, strncmp(sFull, sTarget, nPattern) == 0);
      }
    } else {
      // Slow path: complex pattern (e.g., '*abc', 'a*b', etc.)
      // Must fetch and check full string for each row
      for (int i = 0; i < size; i++) {
        view = &((u8 *)buffer)[i * VEC0_METADATA_TEXT_VIEW_BUFFER_LENGTH];
        nPrefix = ((int *)view)[0];
        sPrefix = (char *)&view[4];

        // For short strings, use cached value directly
        if (nPrefix <= VEC0_METADATA_TEXT_VIEW_DATA_LENGTH) {
          // a 12-byte value fills the view without a NUL terminator
          char zPrefix[VEC0_METADATA_TEXT_VIEW_DATA_LENGTH + 1];
          memcpy(zPrefix, sPrefix, nPrefix);
          zPrefix[nPrefix] = '\0';
          // sqlite3_strglob returns 0 on match, non-zero otherwise
          bitmap_set(b, i, sqlite3_strglob(sTarget, zPrefix) == 0);
          continue;
        }

        // For long strings, fetch full value
        rc = vec0_get_metadata_text_long_value(p, &stmt, metadata_idx,
                                               rowids[i], &nFull, &sFull);
        if (rc != SQLITE_OK) {
          goto done;
        }
        if (nPrefix != nFull) {
          rc = SQLITE_ERROR;
          goto done;
        }

        // Use SQLite's GLOB implementation
        bitmap_set(b, i, sqlite3_strglob(sTarget, sFull) == 0);
      }
    }
    break;
  }

  case VEC0_METADATA_OPERATOR_IS:
  case VEC0_METADATA_OPERATOR_ISNOT: {
    // Should never be reached - IS/ISNOT are mapped to EQ/NE before the switch
    break;
  }

  case VEC0_METADATA_OPERATOR_ISNULL: {
    // IS NULL always returns false (metadata columns don't support NULL)
    // All bits stay 0 (already initialized)
    break;
  }

  case VEC0_METADATA_OPERATOR_ISNOTNULL: {
    // IS NOT NULL always returns true (metadata columns don't support NULL)
    for (int i = 0; i < size; i++) {
      bitmap_set(b, i, 1);
    }
    break;
  }
  }
  rc = SQLITE_OK;

done:
  sqlite3_finalize(stmt);
  sqlite3_free(rowids);
  return rc;
}

/**
 * @brief Fill in bitmap of chunk values, whether or not the values match a
 * metadata constraint
 *
 * @param p vec0_vtab
 * @param metadata_idx index of the metatadata column to perfrom constraints on
 * @param value sqlite3_value of the constraints value
 * @param blob sqlite3_blob that is already opened on the metdata column's
 * shadow chunk table
 * @param chunk_rowid rowid of the chunk to calculate on
 * @param b pre-allocated and zero'd out bitmap to write results to
 * @param size size of the chunk
 * @return int SQLITE_OK on success, error code otherwise
 */
int vec0_set_metadata_filter_bitmap(vec0_vtab *p, int metadata_idx,
                                    vec0_metadata_operator op,
                                    vec0_metadata_collation collation,
                                    sqlite3_value *value, sqlite3_blob *blob,
                                    i64 chunk_rowid, u8 *b, int size,
                                    struct Array *aMetadataIn, int argv_idx) {
  // TODO: shouldn't this skip in-valid entries from the chunk's  validity
  // bitmap?

  vec0_metadata_column_kind kind = p->metadata_columns[metadata_idx].kind;
  int constant = vec0_metadata_constant_result(kind, op, value);
  if (constant >= 0) {
    for (int i = 0; i < size; i++) {
      bitmap_set(b, i, constant);
    }
    return SQLITE_OK;
  }

  int rc;
  rc = sqlite3_blob_reopen(blob, chunk_rowid);
  if (rc != SQLITE_OK) {
    return rc;
  }

  int szMatch = 0;
  int blobSize = sqlite3_blob_bytes(blob);
  switch (kind) {
  case VEC0_METADATA_COLUMN_KIND_BOOLEAN: {
    szMatch = blobSize == size / CHAR_BIT;
    break;
  }
  case VEC0_METADATA_COLUMN_KIND_INTEGER: {
    szMatch = blobSize == (int)(size * sizeof(i64));
    break;
  }
  case VEC0_METADATA_COLUMN_KIND_FLOAT: {
    szMatch = blobSize == (int)(size * sizeof(double));
    break;
  }
  case VEC0_METADATA_COLUMN_KIND_TEXT: {
    szMatch = blobSize == size * VEC0_METADATA_TEXT_VIEW_BUFFER_LENGTH;
    break;
  }
  }
  if (!szMatch) {
    return SQLITE_ERROR;
  }
  void *buffer = sqlite3_malloc(blobSize);
  if (!buffer) {
    return SQLITE_NOMEM;
  }
  rc = sqlite3_blob_read(blob, buffer, blobSize, 0);
  if (rc != SQLITE_OK) {
    goto done;
  }
  switch (kind) {
  case VEC0_METADATA_COLUMN_KIND_BOOLEAN: {
    int target = sqlite3_value_int(value);
    switch (op) {
    case VEC0_METADATA_OPERATOR_EQ:
    case VEC0_METADATA_OPERATOR_IS: {
      // EQ and IS behave identically for booleans
      if (target) {
        for (int i = 0; i < size; i++) {
          bitmap_set(b, i, bitmap_get((u8 *)buffer, i));
        }
      } else {
        for (int i = 0; i < size; i++) {
          bitmap_set(b, i, !bitmap_get((u8 *)buffer, i));
        }
      }
      break;
    }
    case VEC0_METADATA_OPERATOR_NE:
    case VEC0_METADATA_OPERATOR_ISNOT: {
      // NE and IS NOT behave identically for booleans
      if (target) {
        for (int i = 0; i < size; i++) {
          bitmap_set(b, i, !bitmap_get((u8 *)buffer, i));
        }
      } else {
        for (int i = 0; i < size; i++) {
          bitmap_set(b, i, bitmap_get((u8 *)buffer, i));
        }
      }
      break;
    }
    case VEC0_METADATA_OPERATOR_ISNULL: {
      // IS NULL always returns false (metadata columns don't support NULL)
      for (int i = 0; i < size; i++) {
        bitmap_set(b, i, 0);
      }
      break;
    }
    case VEC0_METADATA_OPERATOR_ISNOTNULL: {
      // IS NOT NULL always returns true (metadata columns don't support NULL)
      for (int i = 0; i < size; i++) {
        bitmap_set(b, i, 1);
      }
      break;
    }
    default: {
      // Should not reach here if xBestIndex validation works correctly
      break;
    }
    }
    break;
  }
  case VEC0_METADATA_COLUMN_KIND_INTEGER: {
    i64 *array = (i64 *)buffer;
    if (op != VEC0_METADATA_OPERATOR_IN &&
        sqlite3_value_type(value) == SQLITE_FLOAT) {
      double target = sqlite3_value_double(value);
      for (int i = 0; i < size; i++) {
        bitmap_set(b, i,
                   vec0_metadata_operator_holds(
                       op, vec0_compare_i64_double(array[i], target)));
      }
      break;
    }
    i64 target = sqlite3_value_int64(value);
    switch (op) {
    case VEC0_METADATA_OPERATOR_EQ: {
      for (int i = 0; i < size; i++) {
        bitmap_set(b, i, array[i] == target);
      }
      break;
    }
    case VEC0_METADATA_OPERATOR_GT: {
      for (int i = 0; i < size; i++) {
        bitmap_set(b, i, array[i] > target);
      }
      break;
    }
    case VEC0_METADATA_OPERATOR_LE: {
      for (int i = 0; i < size; i++) {
        bitmap_set(b, i, array[i] <= target);
      }
      break;
    }
    case VEC0_METADATA_OPERATOR_LT: {
      for (int i = 0; i < size; i++) {
        bitmap_set(b, i, array[i] < target);
      }
      break;
    }
    case VEC0_METADATA_OPERATOR_GE: {
      for (int i = 0; i < size; i++) {
        bitmap_set(b, i, array[i] >= target);
      }
      break;
    }
    case VEC0_METADATA_OPERATOR_NE: {
      for (int i = 0; i < size; i++) {
        bitmap_set(b, i, array[i] != target);
      }
      break;
    }
    case VEC0_METADATA_OPERATOR_IN: {
      int metadataInIdx = -1;
      for (size_t i = 0; i < aMetadataIn->length; i++) {
        struct Vec0MetadataIn *metadataIn =
            &((struct Vec0MetadataIn *)aMetadataIn->z)[i];
        if (metadataIn->argv_idx == argv_idx) {
          metadataInIdx = i;
          break;
        }
      }
      if (metadataInIdx < 0) {
        rc = SQLITE_ERROR;
        goto done;
      }
      struct Vec0MetadataIn *metadataIn =
          &((struct Vec0MetadataIn *)aMetadataIn->z)[metadataInIdx];
      struct Array *aTarget = &(metadataIn->array);

      // The list was sorted when vec0Filter_knn read it. Upstream (vlasky#10)
      // searches it with bsearch(), whose hard-to-predict branches made short
      // lists slower than the linear scan it replaced. Here each step picks a
      // half with a conditional move instead of a branch: gcc -O3 emits one
      // for the plain conditional, and clang needs VEC0_UNPREDICTABLE.
      const i64 *targets = (const i64 *)aTarget->z;
      size_t length = aTarget->length;
      for (int i = 0; length > 0 && i < size; i++) {
        const i64 *base = targets;
        size_t n = length;
        while (n > 1) {
          size_t half = n / 2;
          base =
              VEC0_UNPREDICTABLE(base[half] <= array[i]) ? base + half : base;
          n -= half;
        }
        if (*base == array[i]) {
          bitmap_set(b, i, 1);
        }
      }
      break;
    }
    case VEC0_METADATA_OPERATOR_LIKE: {
      // should never be reached (LIKE only applies to TEXT columns)
      break;
    }
    case VEC0_METADATA_OPERATOR_GLOB: {
      // should never be reached (GLOB only applies to TEXT columns)
      break;
    }
    case VEC0_METADATA_OPERATOR_IS: {
      // IS behaves like = for non-NULL values
      for (int i = 0; i < size; i++) {
        bitmap_set(b, i, array[i] == target);
      }
      break;
    }
    case VEC0_METADATA_OPERATOR_ISNOT: {
      // IS NOT behaves like != for non-NULL values
      for (int i = 0; i < size; i++) {
        bitmap_set(b, i, array[i] != target);
      }
      break;
    }
    case VEC0_METADATA_OPERATOR_ISNULL: {
      // IS NULL always returns false (metadata columns don't support NULL)
      for (int i = 0; i < size; i++) {
        bitmap_set(b, i, 0);
      }
      break;
    }
    case VEC0_METADATA_OPERATOR_ISNOTNULL: {
      // IS NOT NULL always returns true (metadata columns don't support NULL)
      for (int i = 0; i < size; i++) {
        bitmap_set(b, i, 1);
      }
      break;
    }
    }
    break;
  }
  case VEC0_METADATA_COLUMN_KIND_FLOAT: {
    double *array = (double *)buffer;
    if (sqlite3_value_type(value) == SQLITE_INTEGER) {
      i64 target = sqlite3_value_int64(value);
      for (int i = 0; i < size; i++) {
        bitmap_set(b, i,
                   vec0_metadata_operator_holds(
                       op, -vec0_compare_i64_double(target, array[i])));
      }
      break;
    }
    double target = sqlite3_value_double(value);
    switch (op) {
    case VEC0_METADATA_OPERATOR_EQ: {
      for (int i = 0; i < size; i++) {
        bitmap_set(b, i, array[i] == target);
      }
      break;
    }
    case VEC0_METADATA_OPERATOR_GT: {
      for (int i = 0; i < size; i++) {
        bitmap_set(b, i, array[i] > target);
      }
      break;
    }
    case VEC0_METADATA_OPERATOR_LE: {
      for (int i = 0; i < size; i++) {
        bitmap_set(b, i, array[i] <= target);
      }
      break;
    }
    case VEC0_METADATA_OPERATOR_LT: {
      for (int i = 0; i < size; i++) {
        bitmap_set(b, i, array[i] < target);
      }
      break;
    }
    case VEC0_METADATA_OPERATOR_GE: {
      for (int i = 0; i < size; i++) {
        bitmap_set(b, i, array[i] >= target);
      }
      break;
    }
    case VEC0_METADATA_OPERATOR_NE: {
      for (int i = 0; i < size; i++) {
        bitmap_set(b, i, array[i] != target);
      }
      break;
    }
    case VEC0_METADATA_OPERATOR_IN: {
      // should never be reached
      break;
    }
    case VEC0_METADATA_OPERATOR_LIKE: {
      // should never be reached (LIKE only applies to TEXT columns)
      break;
    }
    case VEC0_METADATA_OPERATOR_GLOB: {
      // should never be reached (GLOB only applies to TEXT columns)
      break;
    }
    case VEC0_METADATA_OPERATOR_IS: {
      // IS behaves like = for non-NULL values
      for (int i = 0; i < size; i++) {
        bitmap_set(b, i, array[i] == target);
      }
      break;
    }
    case VEC0_METADATA_OPERATOR_ISNOT: {
      // IS NOT behaves like != for non-NULL values
      for (int i = 0; i < size; i++) {
        bitmap_set(b, i, array[i] != target);
      }
      break;
    }
    case VEC0_METADATA_OPERATOR_ISNULL: {
      // IS NULL always returns false (metadata columns don't support NULL)
      for (int i = 0; i < size; i++) {
        bitmap_set(b, i, 0);
      }
      break;
    }
    case VEC0_METADATA_OPERATOR_ISNOTNULL: {
      // IS NOT NULL always returns true (metadata columns don't support NULL)
      for (int i = 0; i < size; i++) {
        bitmap_set(b, i, 1);
      }
      break;
    }
    }
    break;
  }
  case VEC0_METADATA_COLUMN_KIND_TEXT: {
    rc = vec0_metadata_filter_text(p, value, buffer, size, op, collation, b,
                                   metadata_idx, chunk_rowid, aMetadataIn,
                                   argv_idx);
    if (rc != SQLITE_OK) {
      goto done;
    }
    break;
  }
  }
done:
  sqlite3_free(buffer);
  return rc;
}

int vec0Filter_knn_chunks_iter(vec0_vtab *p, sqlite3_stmt *stmtChunks,
                               struct VectorColumnDefinition *vector_column,
                               int vectorColumnIdx, struct Array *arrayRowidsIn,
                               struct Array *aMetadataIn, const char *idxStr,
                               int argc, sqlite3_value **argv,
                               void *queryVector, i64 k, i64 **out_topk_rowids,
                               f32 **out_topk_distances, i64 *out_used) {
  // for each chunk, get top min(k, chunk_size) rowid + distances to query vec.
  // then reconcile all topk_chunks for a true top k.
  // output only rowids + distances for now

  int rc = SQLITE_OK;
  sqlite3_blob *blobVectors = NULL;

  void *baseVectors = NULL; // memory: chunk_size * dimensions * element_size

  // OWNED BY CALLER ON SUCCESS
  i64 *topk_rowids = NULL; // memory: k * 4
  // OWNED BY CALLER ON SUCCESS
  f32 *topk_distances = NULL; // memory: k * 4

  i64 *tmp_topk_rowids = NULL;    // memory: k * 4
  f32 *tmp_topk_distances = NULL; // memory: k * 4
  f32 *chunk_distances = NULL;    // memory: chunk_size * 4
  u8 *b = NULL;                   // memory: chunk_size / 8
  i32 *chunk_topk_idxs = NULL;    // memory: k * 4
  u8 *bmRowids = NULL;            // memory: chunk_size / 8
  u8 *bmMetadata = NULL;          // memory: chunk_size / 8
  //                        // total: a lot???

  // 6 * (k * 4) + (k * 2) + (chunk_size / 8) + (chunk_size * dimensions * 4)

  topk_rowids = sqlite3_malloc(k * sizeof(i64));
  if (!topk_rowids) {
    rc = SQLITE_NOMEM;
    goto cleanup;
  }
  memset(topk_rowids, 0, k * sizeof(i64));

  topk_distances = sqlite3_malloc(k * sizeof(f32));
  if (!topk_distances) {
    rc = SQLITE_NOMEM;
    goto cleanup;
  }
  memset(topk_distances, 0, k * sizeof(f32));

  tmp_topk_rowids = sqlite3_malloc(k * sizeof(i64));
  if (!tmp_topk_rowids) {
    rc = SQLITE_NOMEM;
    goto cleanup;
  }
  memset(tmp_topk_rowids, 0, k * sizeof(i64));

  tmp_topk_distances = sqlite3_malloc(k * sizeof(f32));
  if (!tmp_topk_distances) {
    rc = SQLITE_NOMEM;
    goto cleanup;
  }
  memset(tmp_topk_distances, 0, k * sizeof(f32));

  i64 k_used = 0;
  i64 baseVectorsSize = p->chunk_size * vector_column_byte_size(*vector_column);
  baseVectors = sqlite3_malloc(baseVectorsSize);
  if (!baseVectors) {
    rc = SQLITE_NOMEM;
    goto cleanup;
  }

  chunk_distances = sqlite3_malloc(p->chunk_size * sizeof(f32));
  if (!chunk_distances) {
    rc = SQLITE_NOMEM;
    goto cleanup;
  }

  b = bitmap_new(p->chunk_size);
  if (!b) {
    rc = SQLITE_NOMEM;
    goto cleanup;
  }

  chunk_topk_idxs = sqlite3_malloc(k * sizeof(i32));
  if (!chunk_topk_idxs) {
    rc = SQLITE_NOMEM;
    goto cleanup;
  }

  bmRowids = arrayRowidsIn ? bitmap_new(p->chunk_size) : NULL;
  if (arrayRowidsIn && !bmRowids) {
    rc = SQLITE_NOMEM;
    goto cleanup;
  }

  sqlite3_blob *metadataBlobs[VEC0_MAX_METADATA_COLUMNS];
  memset(metadataBlobs, 0, sizeof(sqlite3_blob *) * VEC0_MAX_METADATA_COLUMNS);

  bmMetadata = bitmap_new(p->chunk_size);
  if (!bmMetadata) {
    rc = SQLITE_NOMEM;
    goto cleanup;
  }

  int idxStrLength = strlen(idxStr);
  int numValueEntries = (idxStrLength - 1) / 4;
  assert(numValueEntries == argc);
  int hasMetadataFilters = 0;
  int hasDistanceConstraints = 0;
  for (int i = 0; i < argc; i++) {
    int idx = 1 + (i * 4);
    char kind = idxStr[idx + 0];
    if (kind == VEC0_IDXSTR_KIND_METADATA_CONSTRAINT) {
      hasMetadataFilters = 1;
    } else if (kind == VEC0_IDXSTR_KIND_KNN_DISTANCE_CONSTRAINT) {
      hasDistanceConstraints = 1;
    }
  }

  while (true) {
    rc = sqlite3_step(stmtChunks);
    if (rc == SQLITE_DONE) {
      break;
    }
    if (rc != SQLITE_ROW) {
      vtab_set_error(&p->base, "chunks iter error");
      rc = vec0_error_rc(rc);
      goto cleanup;
    }
    memset(chunk_distances, 0, p->chunk_size * sizeof(f32));
    memset(chunk_topk_idxs, 0, k * sizeof(i32));
    bitmap_clear(b, p->chunk_size);

    i64 chunk_id = sqlite3_column_int64(stmtChunks, 0);
    unsigned char *chunkValidity =
        (unsigned char *)sqlite3_column_blob(stmtChunks, 1);
    i64 validitySize = sqlite3_column_bytes(stmtChunks, 1);
    if (validitySize != p->chunk_size / CHAR_BIT) {
      // IMP: V05271_22109
      vtab_set_error(
          &p->base,
          "chunk validity size doesn't match - expected %lld, found %lld",
          p->chunk_size / CHAR_BIT, validitySize);
      rc = SQLITE_ERROR;
      goto cleanup;
    }

    i64 *chunkRowids = (i64 *)sqlite3_column_blob(stmtChunks, 2);
    i64 rowidsSize = sqlite3_column_bytes(stmtChunks, 2);
    if (rowidsSize != (i64)(p->chunk_size * sizeof(i64))) {
      // IMP: V02796_19635
      vtab_set_error(
          &p->base,
          "chunk rowids size doesn't match - expected %lld, found %lld",
          p->chunk_size * sizeof(i64), rowidsSize);
      rc = SQLITE_ERROR;
      goto cleanup;
    }

    bitmap_copy(b, chunkValidity, p->chunk_size);
    if (arrayRowidsIn) {
      bitmap_clear(bmRowids, p->chunk_size);

      for (int i = 0; i < p->chunk_size; i++) {
        if (!bitmap_get(chunkValidity, i)) {
          continue;
        }
        i64 rowid = chunkRowids[i];
        void *in = bsearch(&rowid, arrayRowidsIn->z, arrayRowidsIn->length,
                           sizeof(i64), _cmp);
        bitmap_set(bmRowids, i, in ? 1 : 0);
      }
      bitmap_and_inplace(b, bmRowids, p->chunk_size);
    }

    if (hasMetadataFilters) {
      for (int i = 0; i < argc; i++) {
        int idx = 1 + (i * 4);
        char kind = idxStr[idx + 0];
        if (kind != VEC0_IDXSTR_KIND_METADATA_CONSTRAINT) {
          continue;
        }
        int metadata_idx = idxStr[idx + 1] - 'A';
        int operator = idxStr[idx + 2];
        int collation = idxStr[idx + 3];

        if (!metadataBlobs[metadata_idx]) {
          rc = sqlite3_blob_open(
              p->db, p->schemaName, p->shadowMetadataChunksNames[metadata_idx],
              "data", chunk_id, 0, &metadataBlobs[metadata_idx]);
          if (rc != SQLITE_OK) {
            vtab_set_error(&p->base, "Could not open metadata blob");
            goto cleanup;
          }
        }

        bitmap_clear(bmMetadata, p->chunk_size);
        rc = vec0_set_metadata_filter_bitmap(
            p, metadata_idx, operator, collation, argv[i],
            metadataBlobs[metadata_idx], chunk_id, bmMetadata, p->chunk_size,
            aMetadataIn, i);
        if (rc != SQLITE_OK) {
          vtab_set_error(&p->base, "Could not filter metadata fields");
          goto cleanup;
        }
        bitmap_and_inplace(b, bmMetadata, p->chunk_size);
      }
    }

    // A chunk whose rowid and metadata filters keep no row offers no
    // candidate, so its vectors are never read.
    if (!bitmap_any(b, p->chunk_size)) {
      continue;
    }

    // open the vector chunk blob for the current chunk
    rc = sqlite3_blob_open(p->db, p->schemaName,
                           p->shadowVectorChunksNames[vectorColumnIdx],
                           "vectors", chunk_id, 0, &blobVectors);
    if (rc != SQLITE_OK) {
      vtab_set_error(&p->base, "could not open vectors blob for chunk %lld",
                     chunk_id);
      rc = vec0_error_rc(rc);
      goto cleanup;
    }

    i64 currentBaseVectorsSize = sqlite3_blob_bytes(blobVectors);
    i64 expectedBaseVectorsSize =
        p->chunk_size * vector_column_byte_size(*vector_column);
    if (currentBaseVectorsSize != expectedBaseVectorsSize) {
      // IMP: V16465_00535
      vtab_set_error(
          &p->base,
          "vectors blob size doesn't match - expected %lld, found %lld",
          expectedBaseVectorsSize, currentBaseVectorsSize);
      rc = SQLITE_ERROR;
      goto cleanup;
    }
    rc = sqlite3_blob_read(blobVectors, baseVectors, currentBaseVectorsSize, 0);

    if (rc != SQLITE_OK) {
      vtab_set_error(&p->base, "vectors blob read error for %lld", chunk_id);
      rc = SQLITE_ERROR;
      goto cleanup;
    }

    for (int i = 0; i < p->chunk_size; i++) {
      if (!bitmap_get(b, i)) {
        continue;
      };

      f32 result = 0.0f;
      switch (vector_column->element_type) {
      case SQLITE_VEC_ELEMENT_TYPE_FLOAT32: {
        const f32 *base_i =
            ((f32 *)baseVectors) + (i * vector_column->dimensions);
        switch (vector_column->distance_metric) {
        case VEC0_DISTANCE_METRIC_L2: {
          result = distance_l2_sqr_float(base_i, (f32 *)queryVector,
                                         &vector_column->dimensions);
          break;
        }
        case VEC0_DISTANCE_METRIC_L1: {
          result = distance_l1_f32(base_i, (f32 *)queryVector,
                                   &vector_column->dimensions);
          break;
        }
        case VEC0_DISTANCE_METRIC_COSINE: {
          result = distance_cosine_float(base_i, (f32 *)queryVector,
                                         &vector_column->dimensions);
          break;
        }
        }
        break;
      }
      case SQLITE_VEC_ELEMENT_TYPE_INT8: {
        const i8 *base_i =
            ((i8 *)baseVectors) + (i * vector_column->dimensions);
        switch (vector_column->distance_metric) {
        case VEC0_DISTANCE_METRIC_L2: {
          result = distance_l2_sqr_int8(base_i, (i8 *)queryVector,
                                        &vector_column->dimensions);
          break;
        }
        case VEC0_DISTANCE_METRIC_L1: {
          result = distance_l1_int8(base_i, (i8 *)queryVector,
                                    &vector_column->dimensions);
          break;
        }
        case VEC0_DISTANCE_METRIC_COSINE: {
          result = distance_cosine_int8(base_i, (i8 *)queryVector,
                                        &vector_column->dimensions);
          break;
        }
        }

        break;
      }
      case SQLITE_VEC_ELEMENT_TYPE_BIT: {
        const u8 *base_i =
            ((u8 *)baseVectors) + (i * (vector_column->dimensions / CHAR_BIT));
        result = distance_hamming(base_i, (u8 *)queryVector,
                                  &vector_column->dimensions);
        break;
      }
      }

      chunk_distances[i] = result;
    }

    if (hasDistanceConstraints) {
      for (int i = 0; i < argc; i++) {
        int idx = 1 + (i * 4);
        char kind = idxStr[idx + 0];
        if (kind != VEC0_IDXSTR_KIND_KNN_DISTANCE_CONSTRAINT) {
          continue;
        }
        vec0_distance_constraint_operator op = idxStr[idx + 1];

        int type = sqlite3_value_type(argv[i]);
        if (type != SQLITE_INTEGER && type != SQLITE_FLOAT) {
          // No distance compares with NULL, and every distance is less than
          // any TEXT or BLOB.
          int keep =
              type != SQLITE_NULL && (op == VEC0_DISTANCE_CONSTRAINT_LT ||
                                      op == VEC0_DISTANCE_CONSTRAINT_LE);
          if (!keep) {
            for (int j = 0; j < p->chunk_size; j++) {
              bitmap_set(b, j, 0);
            }
          }
          continue;
        }
        // Note: SQLite provides distance constraint values as f64 (double), but
        // we cast to f32 (float) for comparison. This matches the precision of
        // our internal distance calculations (which use f32) and avoids
        // precision mismatches. May result in minor precision loss for very
        // small differences.
        f32 target = (f32)sqlite3_value_double(argv[i]);

        switch (op) {
        case VEC0_DISTANCE_CONSTRAINT_GE: {
          for (int j = 0; j < p->chunk_size; j++) {
            if (bitmap_get(b, j) && !(chunk_distances[j] >= target)) {
              bitmap_set(b, j, 0);
            }
          }
          break;
        }
        case VEC0_DISTANCE_CONSTRAINT_GT: {
          for (int j = 0; j < p->chunk_size; j++) {
            if (bitmap_get(b, j) && !(chunk_distances[j] > target)) {
              bitmap_set(b, j, 0);
            }
          }
          break;
        }
        case VEC0_DISTANCE_CONSTRAINT_LE: {
          for (int j = 0; j < p->chunk_size; j++) {
            if (bitmap_get(b, j) && !(chunk_distances[j] <= target)) {
              bitmap_set(b, j, 0);
            }
          }
          break;
        }
        case VEC0_DISTANCE_CONSTRAINT_LT: {
          for (int j = 0; j < p->chunk_size; j++) {
            if (bitmap_get(b, j) && !(chunk_distances[j] < target)) {
              bitmap_set(b, j, 0);
            }
          }
          break;
        }
        }
      }
    }

    int used1;
    min_idx(chunk_distances, p->chunk_size, b, chunk_topk_idxs,
            min(k, p->chunk_size), &used1);

    i64 used;
    merge_sorted_lists(topk_distances, topk_rowids, k_used, chunk_distances,
                       chunkRowids, chunk_topk_idxs,
                       min(min(k, p->chunk_size), used1), tmp_topk_distances,
                       tmp_topk_rowids, k, &used);

    for (int i = 0; i < used; i++) {
      topk_rowids[i] = tmp_topk_rowids[i];
      topk_distances[i] = tmp_topk_distances[i];
    }
    k_used = used;
    // blobVectors is always opened with read-only permissions, so this never
    // fails.
    sqlite3_blob_close(blobVectors);
    blobVectors = NULL;
  }

  *out_topk_rowids = topk_rowids;
  *out_topk_distances = topk_distances;
  *out_used = k_used;
  rc = SQLITE_OK;

cleanup:
  if (rc != SQLITE_OK) {
    sqlite3_free(topk_rowids);
    sqlite3_free(topk_distances);
  }
  sqlite3_free(chunk_topk_idxs);
  sqlite3_free(tmp_topk_rowids);
  sqlite3_free(tmp_topk_distances);
  sqlite3_free(b);
  sqlite3_free(bmRowids);
  sqlite3_free(baseVectors);
  sqlite3_free(chunk_distances);
  sqlite3_free(bmMetadata);
  for (int i = 0; i < VEC0_MAX_METADATA_COLUMNS; i++) {
    sqlite3_blob_close(metadataBlobs[i]);
  }
  // blobVectors is always opened with read-only permissions, so this never
  // fails.
  sqlite3_blob_close(blobVectors);
  return rc;
}

/**
 * Compute pairwise distance between two vectors stored in the vec0 table's
 * native format.  Handles float32, int8, and bit element types with the
 * appropriate metric (L2, cosine, L1, hamming).
 */
static f32 vec0_compute_distance(struct VectorColumnDefinition *vector_column,
                                 const void *a, const void *b) {
  size_t dims = vector_column->dimensions;
  switch (vector_column->element_type) {
  case SQLITE_VEC_ELEMENT_TYPE_FLOAT32:
    switch (vector_column->distance_metric) {
    case VEC0_DISTANCE_METRIC_L2:
      return distance_l2_sqr_float(a, b, &dims);
    case VEC0_DISTANCE_METRIC_L1:
      return (f32)distance_l1_f32(a, b, &dims);
    case VEC0_DISTANCE_METRIC_COSINE:
      return distance_cosine_float(a, b, &dims);
    }
    break;
  case SQLITE_VEC_ELEMENT_TYPE_INT8:
    switch (vector_column->distance_metric) {
    case VEC0_DISTANCE_METRIC_L2:
      return distance_l2_sqr_int8(a, b, &dims);
    case VEC0_DISTANCE_METRIC_L1:
      return (f32)distance_l1_int8(a, b, &dims);
    case VEC0_DISTANCE_METRIC_COSINE:
      return distance_cosine_int8(a, b, &dims);
    }
    break;
  case SQLITE_VEC_ELEMENT_TYPE_BIT:
    return distance_hamming(a, b, &dims);
  }
  return 0.0f;
}

/**
 * MMR greedy reranking of KNN results.
 *
 * Loads vectors for top-k candidates, then iteratively selects the
 * candidate with the best MMR score:
 *   MMR(d) = lambda * relevance(d) - (1-lambda) * max_sim(d, S)
 *
 * where relevance = 1 - normalized_distance, and max_sim is the highest
 * 1 - distance / max_dist between d and any already-selected result, floored
 * at 0, in the column's distance metric, with max_dist the largest candidate
 * distance.
 *
 * Reorders topk_rowids and topk_distances in place.
 * After return, the first *out_n_selected entries are the MMR-selected results.
 */
static int vec0_mmr_rerank(vec0_vtab *p, int vectorColumnIdx,
                           struct VectorColumnDefinition *vector_column,
                           i64 *topk_rowids, f32 *topk_distances, i64 k_used,
                           i64 k_target, f32 mmr_lambda, i64 *out_n_selected) {
  int rc = SQLITE_OK;

  // 1. Allocate vector storage for all candidates
  void **vectors = sqlite3_malloc64(k_used * sizeof(void *));
  if (!vectors)
    return SQLITE_NOMEM;
  memset(vectors, 0, k_used * sizeof(void *));

  f32 *relevance = NULL;
  i64 *out_rowids = NULL;
  f32 *out_distances = NULL;
  f32 *max_sim = NULL;
  u8 *selected = NULL;

  // 2. Load vectors from shadow tables
  for (i64 i = 0; i < k_used; i++) {
    rc = vec0_get_vector_data(p, topk_rowids[i], vectorColumnIdx, &vectors[i],
                              NULL);
    if (rc != SQLITE_OK)
      goto cleanup;
  }

  // 3. Normalize distances to [0, 1] for relevance scoring
  f32 max_dist = 0.0f;
  for (i64 i = 0; i < k_used; i++) {
    if (topk_distances[i] > max_dist)
      max_dist = topk_distances[i];
  }
  if (max_dist < 1e-9f)
    max_dist = 1.0f;

  relevance = sqlite3_malloc64(k_used * sizeof(f32));
  if (!relevance) {
    rc = SQLITE_NOMEM;
    goto cleanup;
  }
  for (i64 i = 0; i < k_used; i++) {
    relevance[i] = 1.0f - (topk_distances[i] / max_dist);
  }

  // 4. Greedy MMR selection. max_sim[i] is candidate i's highest similarity
  // to the results selected so far, raised against each new selection
  // alone, so a step measures each remaining candidate once.
  out_rowids = sqlite3_malloc64(k_target * sizeof(i64));
  out_distances = sqlite3_malloc64(k_target * sizeof(f32));
  max_sim = sqlite3_malloc64(k_used * sizeof(f32));
  selected = sqlite3_malloc64(k_used);
  if (!out_rowids || !out_distances || !max_sim || !selected) {
    rc = SQLITE_NOMEM;
    goto cleanup;
  }
  memset(selected, 0, k_used);
  for (i64 i = 0; i < k_used; i++) {
    max_sim[i] = 0.0f;
  }

  i64 n_selected = 0;
  for (i64 step = 0; step < k_target && step < k_used; step++) {
    f32 best_mmr = -FLT_MAX;
    i64 best_idx = -1;

    for (i64 i = 0; i < k_used; i++) {
      if (selected[i])
        continue;

      f32 mmr_score =
          mmr_lambda * relevance[i] - (1.0f - mmr_lambda) * max_sim[i];
      if (mmr_score > best_mmr) {
        best_mmr = mmr_score;
        best_idx = i;
      }
    }

    if (best_idx < 0)
      break;
    selected[best_idx] = 1;
    out_rowids[step] = topk_rowids[best_idx];
    out_distances[step] = topk_distances[best_idx];
    n_selected++;

    // Departs from upstream (vlasky#11), which also raises max_sim after the
    // last selection. Nothing reads those values, and computing them made
    // k = 1 and k = 2 compute more distances than the nested loop this
    // replaced (4 instead of 0, and 17 instead of 9).
    if (n_selected == k_target)
      break;

    for (i64 i = 0; i < k_used; i++) {
      if (selected[i])
        continue;
      f32 d =
          vec0_compute_distance(vector_column, vectors[i], vectors[best_idx]);
      f32 sim = 1.0f - (d / max_dist);
      if (sim > max_sim[i])
        max_sim[i] = sim;
    }
  }

  // 5. Copy results back to input arrays
  for (i64 i = 0; i < n_selected; i++) {
    topk_rowids[i] = out_rowids[i];
    topk_distances[i] = out_distances[i];
  }
  *out_n_selected = n_selected;

cleanup:
  if (vectors) {
    for (i64 i = 0; i < k_used; i++) {
      sqlite3_free(vectors[i]);
    }
    sqlite3_free(vectors);
  }
  sqlite3_free(relevance);
  sqlite3_free(out_rowids);
  sqlite3_free(out_distances);
  sqlite3_free(max_sim);
  sqlite3_free(selected);
  return rc;
}

// Appends the rowid that a value of a KNN query's `rowid = ?` or
// `rowid in (...)` names to rowids. A value that equals no rowid, or an id that
// is not in the table, appends nothing.
static int vec0_knn_rowids_append(vec0_vtab *p, sqlite3_value *value,
                                  struct Array *rowids) {
  i64 rowid;
  if (p->pkIsText) {
    // vec0 declares a text id column without a type, so a value of another
    // type equals no id, and vec0_rowid_from_id() would convert the integer 5
    // to '5'. SQLite cannot re-check these ids, as it does for the point plan,
    // since a row it dropped would have taken one of the k slots. Like a KNN
    // metadata filter, this sees only the value, so it also finds no id where
    // SQLite would convert the id to a number, as for `id = CAST(5 AS INT)`.
    if (sqlite3_value_type(value) != SQLITE_TEXT) {
      return SQLITE_OK;
    }
    int rc = vec0_rowid_from_id(p, value, &rowid);
    if (rc == SQLITE_EMPTY) {
      return SQLITE_OK;
    }
    if (rc != SQLITE_OK) {
      return rc;
    }
  } else if (!vec0_value_as_rowid(value, &rowid)) {
    return SQLITE_OK;
  }
  return array_append(rowids, &rowid);
}

int vec0Filter_knn(vec0_cursor *pCur, vec0_vtab *p, int idxNum,
                   const char *idxStr, int argc, sqlite3_value **argv) {
  assert(argc == (int)((strlen(idxStr) - 1) / 4));
  int rc;
  struct vec0_query_knn_data *knn_data;

  int vectorColumnIdx = idxNum;
  struct VectorColumnDefinition *vector_column =
      &p->vector_columns[vectorColumnIdx];

  struct Array *arrayRowidsIn = NULL;
  sqlite3_stmt *stmtChunks = NULL;
  void *queryVector;
  size_t dimensions;
  enum VectorElementType elementType;
  vector_cleanup queryVectorCleanup = vector_cleanup_noop;
  char *pzError;
  knn_data = sqlite3_malloc(sizeof(*knn_data));
  if (!knn_data) {
    return SQLITE_NOMEM;
  }
  memset(knn_data, 0, sizeof(*knn_data));
  // array of `struct Vec0MetadataIn`, IF there are any `xxx in (...)` metadata
  // constraints
  struct Array *aMetadataIn = NULL;

  int query_idx = -1;
  int k_idx = -1;
  int rowid_in_idx = -1;
  int rowid_eq_idx = -1;
  int mmr_lambda_idx = -1;
  for (int i = 0; i < argc; i++) {
    if (idxStr[1 + (i * 4)] == VEC0_IDXSTR_KIND_KNN_MATCH) {
      query_idx = i;
    }
    if (idxStr[1 + (i * 4)] == VEC0_IDXSTR_KIND_KNN_K) {
      k_idx = i;
    }
    if (idxStr[1 + (i * 4)] == VEC0_IDXSTR_KIND_KNN_ROWID_IN) {
      rowid_in_idx = i;
    }
    if (idxStr[1 + (i * 4)] == VEC0_IDXSTR_KIND_KNN_ROWID_EQ) {
      rowid_eq_idx = i;
    }
    if (idxStr[1 + (i * 4)] == VEC0_IDXSTR_KIND_KNN_MMR_LAMBDA) {
      mmr_lambda_idx = i;
    }
  }
  assert(query_idx >= 0);
  assert(k_idx >= 0);

  // make sure the query vector matches the vector column (type dimensions etc.)
  rc = vector_from_value(argv[query_idx], &queryVector, &dimensions,
                         &elementType, &queryVectorCleanup, &pzError);

  if (rc != SQLITE_OK) {
    vtab_set_error(&p->base,
                   "Query vector on the \"%.*s\" column is invalid: %z",
                   vector_column->name_length, vector_column->name, pzError);
    rc = SQLITE_ERROR;
    goto cleanup;
  }
  if (elementType != vector_column->element_type) {
    vtab_set_error(
        &p->base,
        "Query vector for the \"%.*s\" column is expected to be of type "
        "%s, but a %s vector was provided.",
        vector_column->name_length, vector_column->name,
        vector_subtype_name(vector_column->element_type),
        vector_subtype_name(elementType));
    rc = SQLITE_ERROR;
    goto cleanup;
  }
  if (dimensions != vector_column->dimensions) {
    vtab_set_error(
        &p->base,
        "Dimension mismatch for query vector for the \"%.*s\" column. "
        "Expected %d dimensions but received %d.",
        vector_column->name_length, vector_column->name,
        vector_column->dimensions, dimensions);
    rc = SQLITE_ERROR;
    goto cleanup;
  }

  // numeric affinity, then an integer, as SQLite requires of LIMIT
  i64 k;
  int k_type = sqlite3_value_numeric_type(argv[k_idx]);
  if (!vec0_value_as_i64(argv[k_idx], &k)) {
    vtab_set_error(&p->base,
                   "k value in knn query must be an integer, provided %s",
                   type_name(k_type));
    rc = SQLITE_ERROR;
    goto cleanup;
  }
  if (k < 0) {
    vtab_set_error(
        &p->base, "k value in knn queries must be greater than or equal to 0.");
    rc = SQLITE_ERROR;
    goto cleanup;
  }
#define SQLITE_VEC_VEC0_K_MAX 4096
  if (k > SQLITE_VEC_VEC0_K_MAX) {
    vtab_set_error(
        &p->base,
        "k value in knn query too large, provided %lld and the limit is %lld",
        k, SQLITE_VEC_VEC0_K_MAX);
    rc = SQLITE_ERROR;
    goto cleanup;
  }

  if (k == 0) {
    knn_data->k = 0;
    pCur->knn_data = knn_data;
    pCur->query_plan = VEC0_QUERY_PLAN_KNN;
    rc = SQLITE_OK;
    goto cleanup;
  }

  // MMR: validate lambda and over-fetch candidates
#define SQLITE_VEC_MMR_OVERFETCH_FACTOR 5
  f32 mmr_lambda = -1.0f;
  i64 k_original = k;
  if (mmr_lambda_idx >= 0) {
    // numeric affinity, as SQLite applies to LIMIT, so '0.5' is 0.5
    int mmr_lambda_type = sqlite3_value_numeric_type(argv[mmr_lambda_idx]);
    if (mmr_lambda_type != SQLITE_INTEGER && mmr_lambda_type != SQLITE_FLOAT) {
      vtab_set_error(&p->base,
                     "mmr_lambda value in knn query must be a number between "
                     "0.0 and 1.0, provided %s",
                     type_name(mmr_lambda_type));
      rc = SQLITE_ERROR;
      goto cleanup;
    }
    mmr_lambda = (f32)sqlite3_value_double(argv[mmr_lambda_idx]);
    if (mmr_lambda < 0.0f || mmr_lambda > 1.0f) {
      vtab_set_error(
          &p->base,
          "mmr_lambda value in knn query must be between 0.0 and 1.0, "
          "provided %f",
          (double)mmr_lambda);
      rc = SQLITE_ERROR;
      goto cleanup;
    }
    if (mmr_lambda < 1.0f) {
      i64 k_internal = k * SQLITE_VEC_MMR_OVERFETCH_FACTOR;
      if (k_internal > SQLITE_VEC_VEC0_K_MAX)
        k_internal = SQLITE_VEC_VEC0_K_MAX;
      if (k_internal < k)
        k_internal = k; // overflow guard
      k = k_internal;
    }
  }

  // handle when a `rowid = ?` or `rowid in (...)` operation was provided
  // Array of all the rowids that it names. NULL if neither was provided, which
  // means a "full" scan.
  if (rowid_eq_idx >= 0 || rowid_in_idx >= 0) {
    arrayRowidsIn = sqlite3_malloc(sizeof(*arrayRowidsIn));
    if (!arrayRowidsIn) {
      rc = SQLITE_NOMEM;
      goto cleanup;
    }
    memset(arrayRowidsIn, 0, sizeof(*arrayRowidsIn));

    rc = array_init(arrayRowidsIn, sizeof(i64), 32);
    if (rc != SQLITE_OK) {
      goto cleanup;
    }
    if (rowid_eq_idx >= 0) {
      rc = vec0_knn_rowids_append(p, argv[rowid_eq_idx], arrayRowidsIn);
      if (rc != SQLITE_OK) {
        goto cleanup;
      }
    }
#if COMPILER_SUPPORTS_VTAB_IN
    if (rowid_in_idx >= 0) {
      sqlite3_value *item;
      for (rc = sqlite3_vtab_in_first(argv[rowid_in_idx], &item);
           rc == SQLITE_OK && item;
           rc = sqlite3_vtab_in_next(argv[rowid_in_idx], &item)) {
        rc = vec0_knn_rowids_append(p, item, arrayRowidsIn);
        if (rc != SQLITE_OK) {
          goto cleanup;
        }
      }
      if (rc != SQLITE_DONE) {
        vtab_set_error(&p->base, "error processing rowid in (...) array");
        goto cleanup;
      }
      qsort(arrayRowidsIn->z, arrayRowidsIn->length,
            arrayRowidsIn->element_size, _cmp);
    }
#endif
  }

#if COMPILER_SUPPORTS_VTAB_IN
  for (int i = 0; i < argc; i++) {
    if (!(idxStr[1 + (i * 4)] == VEC0_IDXSTR_KIND_METADATA_CONSTRAINT &&
          idxStr[1 + (i * 4) + 2] == VEC0_METADATA_OPERATOR_IN)) {
      continue;
    }
    int metadata_idx = idxStr[1 + (i * 4) + 1] - 'A';
    if (!aMetadataIn) {
      aMetadataIn = sqlite3_malloc(sizeof(*aMetadataIn));
      if (!aMetadataIn) {
        rc = SQLITE_NOMEM;
        goto cleanup;
      }
      memset(aMetadataIn, 0, sizeof(*aMetadataIn));
      rc = array_init(aMetadataIn, sizeof(struct Vec0MetadataIn), 8);
      if (rc != SQLITE_OK) {
        goto cleanup;
      }
    }

    struct Vec0MetadataIn item;
    memset(&item, 0, sizeof(item));
    item.metadata_idx = metadata_idx;
    item.argv_idx = i;

    switch (p->metadata_columns[metadata_idx].kind) {
    case VEC0_METADATA_COLUMN_KIND_INTEGER: {
      rc = array_init(&item.array, sizeof(i64), 16);
      if (rc != SQLITE_OK) {
        goto cleanup;
      }
      sqlite3_value *entry;
      for (rc = sqlite3_vtab_in_first(argv[i], &entry);
           rc == SQLITE_OK && entry;
           rc = sqlite3_vtab_in_next(argv[i], &entry)) {
        i64 v;
        if (!vec0_value_as_i64(entry, &v)) {
          continue;
        }
        rc = array_append(&item.array, &v);
        if (rc != SQLITE_OK) {
          array_cleanup(&item.array);
          goto cleanup;
        }
      }

      if (rc != SQLITE_DONE) {
        vtab_set_error(
            &p->base,
            "Error fetching next value in `x in (...)` integer expression");
        array_cleanup(&item.array);
        goto cleanup;
      }
      qsort(item.array.z, item.array.length, item.array.element_size, _cmp);

      break;
    }
    case VEC0_METADATA_COLUMN_KIND_TEXT: {
      rc = array_init(&item.array, sizeof(struct Vec0MetadataInTextEntry), 16);
      if (rc != SQLITE_OK) {
        goto cleanup;
      }
      sqlite3_value *entry;
      for (rc = sqlite3_vtab_in_first(argv[i], &entry);
           rc == SQLITE_OK && entry;
           rc = sqlite3_vtab_in_next(argv[i], &entry)) {
        if (sqlite3_value_type(entry) != SQLITE_TEXT) {
          continue;
        }
        const char *s = (const char *)sqlite3_value_text(entry);
        int n = sqlite3_value_bytes(entry);

        struct Vec0MetadataInTextEntry textEntry;
        textEntry.zString = sqlite3_malloc(n + 1);
        if (!textEntry.zString) {
          rc = SQLITE_NOMEM;
          goto item_text_cleanup;
        }
        // copy all n bytes, including any embedded NUL
        memcpy(textEntry.zString, s, n);
        textEntry.zString[n] = '\0';
        textEntry.n = n;
        rc = array_append(&item.array, &textEntry);
        if (rc != SQLITE_OK) {
          sqlite3_free(textEntry.zString);
          goto item_text_cleanup;
        }
      }

      if (rc != SQLITE_DONE) {
        vtab_set_error(
            &p->base,
            "Error fetching next value in `x in (...)` text expression");
        goto item_text_cleanup;
      }

      break;

    // Error cleanup label for TEXT case only. Unlike INTEGER entries (which are
    // plain i64 values), TEXT entries contain heap-allocated zString pointers
    // that must be freed before array_cleanup(). This label is only reachable
    // via goto from error paths within this case block.
    item_text_cleanup:
      vec0_metadata_in_text_cleanup(&item.array);
      goto cleanup;
    }
    default: {
      vtab_set_error(&p->base, "Internal sqlite-vec error");
      goto cleanup;
    }
    }

    rc = array_append(aMetadataIn, &item);
    if (rc != SQLITE_OK) {
      // Clean up item that couldn't be appended
      if (p->metadata_columns[metadata_idx].kind ==
          VEC0_METADATA_COLUMN_KIND_TEXT) {
        vec0_metadata_in_text_cleanup(&item.array);
      } else {
        array_cleanup(&item.array);
      }
      goto cleanup;
    }
  }
#endif

  rc = vec0_chunks_iter(p, idxStr, argc, argv, &stmtChunks);
  if (rc != SQLITE_OK) {
    // IMP: V06942_23781
    vtab_set_error(&p->base, "Error preparing stmtChunk: %s",
                   sqlite3_errmsg(p->db));
    goto cleanup;
  }

  i64 *topk_rowids = NULL;
  f32 *topk_distances = NULL;
  i64 k_used = 0;
  rc = vec0Filter_knn_chunks_iter(p, stmtChunks, vector_column, vectorColumnIdx,
                                  arrayRowidsIn, aMetadataIn, idxStr, argc,
                                  argv, queryVector, k, &topk_rowids,
                                  &topk_distances, &k_used);
  if (rc != SQLITE_OK) {
    goto cleanup;
  }
  // knn_data owns the top-k buffers from here, so the error path frees them.
  knn_data->rowids = topk_rowids;
  knn_data->distances = topk_distances;

  // MMR reranking: select diverse subset from over-fetched candidates
  if (mmr_lambda >= 0.0f && mmr_lambda < 1.0f && k_used > k_original) {
    i64 n_selected = 0;
    rc = vec0_mmr_rerank(p, vectorColumnIdx, vector_column, topk_rowids,
                         topk_distances, k_used, k_original, mmr_lambda,
                         &n_selected);
    if (rc != SQLITE_OK)
      goto cleanup;
    k_used = n_selected;
    k = k_original;
  }

  knn_data->current_idx = 0;
  knn_data->k = k;
  knn_data->k_used = k_used;

  pCur->knn_data = knn_data;
  pCur->query_plan = VEC0_QUERY_PLAN_KNN;
  rc = SQLITE_OK;

cleanup:
  sqlite3_finalize(stmtChunks);
  array_cleanup(arrayRowidsIn);
  sqlite3_free(arrayRowidsIn);
  queryVectorCleanup(queryVector);
  if (aMetadataIn) {
    for (size_t i = 0; i < aMetadataIn->length; i++) {
      struct Vec0MetadataIn *item =
          &((struct Vec0MetadataIn *)aMetadataIn->z)[i];
      if (p->metadata_columns[item->metadata_idx].kind ==
          VEC0_METADATA_COLUMN_KIND_TEXT) {
        vec0_metadata_in_text_cleanup(&item->array);
      } else {
        array_cleanup(&item->array);
      }
    }
    array_cleanup(aMetadataIn);
  }

  sqlite3_free(aMetadataIn);

  // On error, knn_data was never assigned to the cursor, so free it here.
  // On success, it's owned by pCur->knn_data and will be freed by
  // vec0_cursor_clear.
  if (rc != SQLITE_OK) {
    vec0_query_knn_data_clear(knn_data);
    sqlite3_free(knn_data);
  }

  return rc;
}

int vec0Filter_fullscan(vec0_vtab *p, vec0_cursor *pCur) {
  int rc;
  char *zSql;
  struct vec0_query_fullscan_data *fullscan_data;

  fullscan_data = sqlite3_malloc(sizeof(*fullscan_data));
  if (!fullscan_data) {
    return SQLITE_NOMEM;
  }
  memset(fullscan_data, 0, sizeof(*fullscan_data));

  zSql = sqlite3_mprintf(" SELECT rowid "
                         " FROM " VEC0_SHADOW_ROWIDS_NAME
                         " ORDER by chunk_id, chunk_offset ",
                         p->schemaName, p->tableName);
  if (!zSql) {
    rc = SQLITE_NOMEM;
    goto error;
  }
  rc = sqlite3_prepare_v2(p->db, zSql, -1, &fullscan_data->rowids_stmt, NULL);
  sqlite3_free(zSql);
  if (rc != SQLITE_OK) {
    // IMP: V09901_26739
    vtab_set_error(&p->base, "Error preparing rowid scan: %s",
                   sqlite3_errmsg(p->db));
    goto error;
  }

  rc = sqlite3_step(fullscan_data->rowids_stmt);

  // DONE when there's no rowids, ROW when there are, both "success"
  if (!(rc == SQLITE_ROW || rc == SQLITE_DONE)) {
    goto error;
  }

  fullscan_data->done = rc == SQLITE_DONE;
  pCur->query_plan = VEC0_QUERY_PLAN_FULLSCAN;
  pCur->fullscan_data = fullscan_data;
  return SQLITE_OK;

error:
  vec0_query_fullscan_data_clear(fullscan_data);
  sqlite3_free(fullscan_data);
  return rc;
}

int vec0Filter_point(vec0_cursor *pCur, vec0_vtab *p, int argc,
                     sqlite3_value **argv) {
  int rc;
  assert(argc == 1);
  i64 rowid = 0;
  struct vec0_query_point_data *point_data = NULL;

  point_data = sqlite3_malloc(sizeof(*point_data));
  if (!point_data) {
    rc = SQLITE_NOMEM;
    goto error;
  }
  memset(point_data, 0, sizeof(*point_data));

  if (p->pkIsText) {
    rc = vec0_rowid_from_id(p, argv[0], &rowid);
    if (rc == SQLITE_EMPTY) {
      goto eof;
    }
    if (rc != SQLITE_OK) {
      goto error;
    }
  } else if (!vec0_value_as_rowid(argv[0], &rowid)) {
    goto eof;
  }

  for (int i = 0; i < p->numVectorColumns; i++) {
    rc = vec0_get_vector_data(p, rowid, i, &point_data->vectors[i], NULL);
    if (rc == SQLITE_EMPTY) {
      // No such row, which is not an error: drop the message
      // vec0_get_vector_data() set, which SQLite would report for any later
      // error in the statement that sets no message of its own.
      sqlite3_free(p->base.zErrMsg);
      p->base.zErrMsg = NULL;
      goto eof;
    }
    if (rc != SQLITE_OK) {
      goto error;
    }
  }

  point_data->rowid = rowid;
  point_data->done = 0;
  pCur->point_data = point_data;
  pCur->query_plan = VEC0_QUERY_PLAN_POINT;
  return SQLITE_OK;

eof:
  point_data->rowid = rowid;
  point_data->done = 1;
  pCur->point_data = point_data;
  pCur->query_plan = VEC0_QUERY_PLAN_POINT;
  return SQLITE_OK;

error:
  vec0_query_point_data_clear(point_data);
  sqlite3_free(point_data);
  return rc;
}

static int vec0Filter(sqlite3_vtab_cursor *pVtabCursor, int idxNum,
                      const char *idxStr, int argc, sqlite3_value **argv) {
  vec0_vtab *p = (vec0_vtab *)pVtabCursor->pVtab;
  vec0_cursor *pCur = (vec0_cursor *)pVtabCursor;
  vec0_cursor_clear(pCur);

  int idxStrLength = strlen(idxStr);
  if (idxStrLength <= 0) {
    return SQLITE_ERROR;
  }
  if ((idxStrLength - 1) % 4 != 0) {
    return SQLITE_ERROR;
  }
  int numValueEntries = (idxStrLength - 1) / 4;
  if (numValueEntries != argc) {
    return SQLITE_ERROR;
  }

  char query_plan = idxStr[0];
  switch (query_plan) {
  case VEC0_QUERY_PLAN_FULLSCAN:
    return vec0_interrupt_result(&p->base, vec0Filter_fullscan(p, pCur));
  case VEC0_QUERY_PLAN_KNN:
    return vec0_interrupt_result(
        &p->base, vec0Filter_knn(pCur, p, idxNum, idxStr, argc, argv));
  case VEC0_QUERY_PLAN_POINT:
    return vec0_interrupt_result(&p->base,
                                 vec0Filter_point(pCur, p, argc, argv));
  default:
    vtab_set_error(pVtabCursor->pVtab, "unknown idxStr '%s'", idxStr);
    return SQLITE_ERROR;
  }
}

static int vec0Rowid(sqlite3_vtab_cursor *cur, sqlite_int64 *pRowid) {
  vec0_cursor *pCur = (vec0_cursor *)cur;
  switch (pCur->query_plan) {
  case VEC0_QUERY_PLAN_FULLSCAN: {
    *pRowid = sqlite3_column_int64(pCur->fullscan_data->rowids_stmt, 0);
    return SQLITE_OK;
  }
  case VEC0_QUERY_PLAN_POINT: {
    *pRowid = pCur->point_data->rowid;
    return SQLITE_OK;
  }
  case VEC0_QUERY_PLAN_KNN: {
    *pRowid = pCur->knn_data->rowids[pCur->knn_data->current_idx];
    return SQLITE_OK;
  }
  }
  return SQLITE_ERROR;
}

static int vec0Next(sqlite3_vtab_cursor *cur) {
  vec0_cursor *pCur = (vec0_cursor *)cur;
  switch (pCur->query_plan) {
  case VEC0_QUERY_PLAN_FULLSCAN: {
    if (!pCur->fullscan_data) {
      return SQLITE_ERROR;
    }
    int rc = sqlite3_step(pCur->fullscan_data->rowids_stmt);
    if (rc == SQLITE_DONE) {
      pCur->fullscan_data->done = 1;
      return SQLITE_OK;
    }
    if (rc == SQLITE_ROW) {
      return SQLITE_OK;
    }
    return vec0_error_rc(rc);
  }
  case VEC0_QUERY_PLAN_KNN: {
    if (!pCur->knn_data) {
      return SQLITE_ERROR;
    }

    pCur->knn_data->current_idx++;
    return SQLITE_OK;
  }
  case VEC0_QUERY_PLAN_POINT: {
    if (!pCur->point_data) {
      return SQLITE_ERROR;
    }
    pCur->point_data->done = 1;
    return SQLITE_OK;
  }
  }
  return SQLITE_ERROR;
}

static int vec0Eof(sqlite3_vtab_cursor *cur) {
  vec0_cursor *pCur = (vec0_cursor *)cur;
  switch (pCur->query_plan) {
  case VEC0_QUERY_PLAN_FULLSCAN: {
    if (!pCur->fullscan_data) {
      return 1;
    }
    return pCur->fullscan_data->done;
  }
  case VEC0_QUERY_PLAN_KNN: {
    if (!pCur->knn_data) {
      return 1;
    }
    // return (pCur->knn_data->current_idx >= pCur->knn_data->k) ||
    // (pCur->knn_data->distances[pCur->knn_data->current_idx] == FLT_MAX);
    return (pCur->knn_data->current_idx >= pCur->knn_data->k_used);
  }
  case VEC0_QUERY_PLAN_POINT: {
    if (!pCur->point_data) {
      return 1;
    }
    return pCur->point_data->done;
  }
  }
  return 1;
}

/**
 * @brief Read the vector of the full scan's current row, through the handle the
 * scan keeps on the row's chunk.
 *
 * The scan visits rows in (chunk_id, chunk_offset) order, so the handle moves
 * to the next chunk with sqlite3_blob_reopen() once per chunk. A write that
 * replaces the chunk's row expires the handle, and sqlite3_blob_read() answers
 * SQLITE_ABORT (https://sqlite.org/c3ref/blob_open.html). A rollback of a
 * transaction that changed the schema invalidates it, and both
 * sqlite3_blob_read() and sqlite3_blob_reopen() answer SQLITE_ABORT_ROLLBACK
 * when the connection has extended result codes on. Either way the read is
 * retried once on a newly opened handle.
 *
 * The row's position is looked up here rather than taken from the scan's
 * statement: that statement sorts every row when the scan starts, so its
 * positions miss a delete, insert or optimize the same connection runs during
 * the scan.
 *
 * @param outVector set to a buffer the caller frees with sqlite3_free()
 */
static int vec0_fullscan_read_vector(vec0_vtab *p,
                                     struct vec0_query_fullscan_data *f,
                                     int vector_idx, void **outVector,
                                     int *outVectorSize) {
  i64 rowid = sqlite3_column_int64(f->rowids_stmt, 0);
  i64 chunk_id;
  i64 chunk_offset;
  int rc = vec0_get_chunk_position(p, rowid, NULL, &chunk_id, &chunk_offset);
  if (rc == SQLITE_EMPTY) {
    vtab_set_error(&p->base, "Could not find a row with rowid %lld", rowid);
    return SQLITE_ERROR;
  }
  if (rc != SQLITE_OK) {
    return rc;
  }
  int size = vector_column_byte_size(p->vector_columns[vector_idx]);
  void *buf = sqlite3_malloc(size);
  if (!buf) {
    return SQLITE_NOMEM;
  }

  sqlite3_blob **blob = &f->vectorBlobs[vector_idx];
  rc = SQLITE_ABORT;
  for (int attempt = 0; attempt < 2 && (rc & 0xff) == SQLITE_ABORT; attempt++) {
    if (*blob && f->vectorBlobChunkIds[vector_idx] != chunk_id) {
      rc = sqlite3_blob_reopen(*blob, chunk_id);
      if (rc != SQLITE_OK) {
        sqlite3_blob_close(*blob);
        *blob = NULL;
      }
      // An invalidated handle is replaced below; any other failure, such as
      // SQLITE_INTERRUPT, fails the read.
      if (rc != SQLITE_OK && (rc & 0xff) != SQLITE_ABORT) {
        sqlite3_free(buf);
        vtab_set_error(
            &p->base,
            "Could not fetch vector data for %lld, opening blob failed", rowid);
        return vec0_error_rc(rc);
      }
    }
    if (!*blob) {
      rc = sqlite3_blob_open(p->db, p->schemaName,
                             p->shadowVectorChunksNames[vector_idx], "vectors",
                             chunk_id, 0, blob);
      if (rc != SQLITE_OK) {
        *blob = NULL;
        sqlite3_free(buf);
        vtab_set_error(
            &p->base,
            "Could not fetch vector data for %lld, opening blob failed", rowid);
        return vec0_error_rc(rc);
      }
    }
    f->vectorBlobChunkIds[vector_idx] = chunk_id;
    rc = sqlite3_blob_read(*blob, buf, size, chunk_offset * size);
    if ((rc & 0xff) == SQLITE_ABORT) {
      sqlite3_blob_close(*blob);
      *blob = NULL;
    }
  }
  if (rc != SQLITE_OK) {
    sqlite3_free(buf);
    vtab_set_error(
        &p->base,
        "Could not fetch vector data for %lld, reading from blob failed",
        rowid);
    return SQLITE_ERROR;
  }
  *outVector = buf;
  *outVectorSize = size;
  return SQLITE_OK;
}

static int vec0Column_fullscan(vec0_vtab *pVtab, vec0_cursor *pCur,
                               sqlite3_context *context, int i) {
  if (!pCur->fullscan_data) {
    sqlite3_result_error(
        context, "Internal sqlite-vec error: fullscan_data is NULL.", -1);
    return SQLITE_ERROR;
  }
  i64 rowid = sqlite3_column_int64(pCur->fullscan_data->rowids_stmt, 0);
  if (i == VEC0_COLUMN_ID) {
    return vec0_result_id(pVtab, context, rowid);
  } else if (vec0_column_idx_is_vector(pVtab, i)) {
    if (sqlite3_vtab_nochange(context)) {
      sqlite3_result_null(context);
      return SQLITE_OK;
    }
    void *v;
    int sz;
    int vector_idx = vec0_column_idx_to_vector_idx(pVtab, i);
    int rc = vec0_fullscan_read_vector(pVtab, pCur->fullscan_data, vector_idx,
                                       &v, &sz);
    if (rc != SQLITE_OK) {
      return rc;
    }
    sqlite3_result_blob(context, v, sz, sqlite3_free);
    sqlite3_result_subtype(context,
                           pVtab->vector_columns[vector_idx].element_type);

  } else if (i == vec0_column_distance_idx(pVtab)) {
    sqlite3_result_null(context);
  } else if (vec0_column_idx_is_partition(pVtab, i)) {
    if (sqlite3_vtab_nochange(context)) {
      return SQLITE_OK;
    }
    int partition_idx = vec0_column_idx_to_partition_idx(pVtab, i);
    sqlite3_value *v;
    int rc =
        vec0_get_partition_value_for_rowid(pVtab, rowid, partition_idx, &v);
    if (rc == SQLITE_OK) {
      sqlite3_result_value(context, v);
      sqlite3_value_free(v);
    } else {
      sqlite3_result_error_code(context, rc);
    }
  } else if (vec0_column_idx_is_auxiliary(pVtab, i)) {
    int auxiliary_idx = vec0_column_idx_to_auxiliary_idx(pVtab, i);
    sqlite3_value *v;
    int rc =
        vec0_get_auxiliary_value_for_rowid(pVtab, rowid, auxiliary_idx, &v);
    if (rc == SQLITE_OK) {
      sqlite3_result_value(context, v);
      sqlite3_value_free(v);
    } else {
      sqlite3_result_error_code(context, rc);
    }
  }

  else if (vec0_column_idx_is_metadata(pVtab, i)) {
    if (sqlite3_vtab_nochange(context)) {
      return SQLITE_OK;
    }
    int metadata_idx = vec0_column_idx_to_metadata_idx(pVtab, i);
    int rc = vec0_result_metadata_value_for_rowid(pVtab, rowid, metadata_idx,
                                                  context);
    if (rc == SQLITE_INTERRUPT) {
      sqlite3_result_error_code(context, rc);
    } else if (rc != SQLITE_OK) {
      // IMP: V15466_32305
      const char *zErr = sqlite3_mprintf(
          "Could not extract metadata value for column %.*s at rowid %lld",
          pVtab->metadata_columns[metadata_idx].name_length,
          pVtab->metadata_columns[metadata_idx].name, rowid);
      if (zErr) {
        sqlite3_result_error(context, zErr, -1);
        sqlite3_free((void *)zErr);
      } else {
        sqlite3_result_error_nomem(context);
      }
    }
  }

  return SQLITE_OK;
}

static int vec0Column_point(vec0_vtab *pVtab, vec0_cursor *pCur,
                            sqlite3_context *context, int i) {
  if (!pCur->point_data) {
    sqlite3_result_error(context,
                         "Internal sqlite-vec error: point_data is NULL.", -1);
    return SQLITE_ERROR;
  }
  if (i == VEC0_COLUMN_ID) {
    return vec0_result_id(pVtab, context, pCur->point_data->rowid);
  } else if (i == vec0_column_distance_idx(pVtab)) {
    sqlite3_result_null(context);
    return SQLITE_OK;
  } else if (vec0_column_idx_is_vector(pVtab, i)) {
    if (sqlite3_vtab_nochange(context)) {
      sqlite3_result_null(context);
      return SQLITE_OK;
    }
    int vector_idx = vec0_column_idx_to_vector_idx(pVtab, i);
    sqlite3_result_blob(
        context, pCur->point_data->vectors[vector_idx],
        vector_column_byte_size(pVtab->vector_columns[vector_idx]),
        SQLITE_TRANSIENT);
    sqlite3_result_subtype(context,
                           pVtab->vector_columns[vector_idx].element_type);
    return SQLITE_OK;
  } else if (vec0_column_idx_is_partition(pVtab, i)) {
    if (sqlite3_vtab_nochange(context)) {
      return SQLITE_OK;
    }
    int partition_idx = vec0_column_idx_to_partition_idx(pVtab, i);
    i64 rowid = pCur->point_data->rowid;
    sqlite3_value *v;
    int rc =
        vec0_get_partition_value_for_rowid(pVtab, rowid, partition_idx, &v);
    if (rc == SQLITE_OK) {
      sqlite3_result_value(context, v);
      sqlite3_value_free(v);
    } else {
      sqlite3_result_error_code(context, rc);
    }
  } else if (vec0_column_idx_is_auxiliary(pVtab, i)) {
    if (sqlite3_vtab_nochange(context)) {
      return SQLITE_OK;
    }
    i64 rowid = pCur->point_data->rowid;
    int auxiliary_idx = vec0_column_idx_to_auxiliary_idx(pVtab, i);
    sqlite3_value *v;
    int rc =
        vec0_get_auxiliary_value_for_rowid(pVtab, rowid, auxiliary_idx, &v);
    if (rc == SQLITE_OK) {
      sqlite3_result_value(context, v);
      sqlite3_value_free(v);
    } else {
      sqlite3_result_error_code(context, rc);
    }
  }

  else if (vec0_column_idx_is_metadata(pVtab, i)) {
    if (sqlite3_vtab_nochange(context)) {
      return SQLITE_OK;
    }
    i64 rowid = pCur->point_data->rowid;
    int metadata_idx = vec0_column_idx_to_metadata_idx(pVtab, i);
    int rc = vec0_result_metadata_value_for_rowid(pVtab, rowid, metadata_idx,
                                                  context);
    if (rc == SQLITE_INTERRUPT) {
      sqlite3_result_error_code(context, rc);
    } else if (rc != SQLITE_OK) {
      const char *zErr = sqlite3_mprintf(
          "Could not extract metadata value for column %.*s at rowid %lld",
          pVtab->metadata_columns[metadata_idx].name_length,
          pVtab->metadata_columns[metadata_idx].name, rowid);
      if (zErr) {
        sqlite3_result_error(context, zErr, -1);
        sqlite3_free((void *)zErr);
      } else {
        sqlite3_result_error_nomem(context);
      }
    }
  }

  return SQLITE_OK;
}

static int vec0Column_knn(vec0_vtab *pVtab, vec0_cursor *pCur,
                          sqlite3_context *context, int i) {
  if (!pCur->knn_data) {
    sqlite3_result_error(context,
                         "Internal sqlite-vec error: knn_data is NULL.", -1);
    return SQLITE_ERROR;
  }
  if (i == VEC0_COLUMN_ID) {
    i64 rowid = pCur->knn_data->rowids[pCur->knn_data->current_idx];
    return vec0_result_id(pVtab, context, rowid);
  } else if (i == vec0_column_distance_idx(pVtab)) {
    sqlite3_result_double(
        context, pCur->knn_data->distances[pCur->knn_data->current_idx]);
    return SQLITE_OK;
  } else if (vec0_column_idx_is_vector(pVtab, i)) {
    if (sqlite3_vtab_nochange(context)) {
      sqlite3_result_null(context);
      return SQLITE_OK;
    }
    void *out;
    int sz;
    int vector_idx = vec0_column_idx_to_vector_idx(pVtab, i);
    int rc = vec0_get_vector_data(
        pVtab, pCur->knn_data->rowids[pCur->knn_data->current_idx], vector_idx,
        &out, &sz);
    if (rc != SQLITE_OK) {
      return rc;
    }
    sqlite3_result_blob(context, out, sz, sqlite3_free);
    sqlite3_result_subtype(context,
                           pVtab->vector_columns[vector_idx].element_type);
    return SQLITE_OK;
  } else if (vec0_column_idx_is_partition(pVtab, i)) {
    if (sqlite3_vtab_nochange(context)) {
      return SQLITE_OK;
    }
    int partition_idx = vec0_column_idx_to_partition_idx(pVtab, i);
    i64 rowid = pCur->knn_data->rowids[pCur->knn_data->current_idx];
    sqlite3_value *v;
    int rc =
        vec0_get_partition_value_for_rowid(pVtab, rowid, partition_idx, &v);
    if (rc == SQLITE_OK) {
      sqlite3_result_value(context, v);
      sqlite3_value_free(v);
    } else {
      sqlite3_result_error_code(context, rc);
    }
  } else if (vec0_column_idx_is_auxiliary(pVtab, i)) {
    int auxiliary_idx = vec0_column_idx_to_auxiliary_idx(pVtab, i);
    i64 rowid = pCur->knn_data->rowids[pCur->knn_data->current_idx];
    sqlite3_value *v;
    int rc =
        vec0_get_auxiliary_value_for_rowid(pVtab, rowid, auxiliary_idx, &v);
    if (rc == SQLITE_OK) {
      sqlite3_result_value(context, v);
      sqlite3_value_free(v);
    } else {
      sqlite3_result_error_code(context, rc);
    }
  }

  else if (vec0_column_idx_is_metadata(pVtab, i)) {
    int metadata_idx = vec0_column_idx_to_metadata_idx(pVtab, i);
    i64 rowid = pCur->knn_data->rowids[pCur->knn_data->current_idx];
    int rc = vec0_result_metadata_value_for_rowid(pVtab, rowid, metadata_idx,
                                                  context);
    if (rc == SQLITE_INTERRUPT) {
      sqlite3_result_error_code(context, rc);
    } else if (rc != SQLITE_OK) {
      const char *zErr = sqlite3_mprintf(
          "Could not extract metadata value for column %.*s at rowid %lld",
          pVtab->metadata_columns[metadata_idx].name_length,
          pVtab->metadata_columns[metadata_idx].name, rowid);
      if (zErr) {
        sqlite3_result_error(context, zErr, -1);
        sqlite3_free((void *)zErr);
      } else {
        sqlite3_result_error_nomem(context);
      }
    }
  }

  return SQLITE_OK;
}

static int vec0Column(sqlite3_vtab_cursor *cur, sqlite3_context *context,
                      int i) {
  vec0_cursor *pCur = (vec0_cursor *)cur;
  vec0_vtab *pVtab = (vec0_vtab *)cur->pVtab;
  switch (pCur->query_plan) {
  case VEC0_QUERY_PLAN_FULLSCAN: {
    return vec0_interrupt_result(cur->pVtab,
                                 vec0Column_fullscan(pVtab, pCur, context, i));
  }
  case VEC0_QUERY_PLAN_KNN: {
    return vec0_interrupt_result(cur->pVtab,
                                 vec0Column_knn(pVtab, pCur, context, i));
  }
  case VEC0_QUERY_PLAN_POINT: {
    return vec0_interrupt_result(cur->pVtab,
                                 vec0Column_point(pVtab, pCur, context, i));
  }
  }
  return SQLITE_OK;
}

/**
 * @brief Handles the "insert rowid" step of a row insert operation of a vec0
 * table.
 *
 * This function will insert a new row into the _rowids vec0 shadow table.
 *
 * @param p: virtual table
 * @param idValue: Value containing the inserted rowid/id value.
 * @param rowid: Output rowid, will point to the "real" i64 rowid
 * value that was inserted
 * @return int SQLITE_OK on success, error code on failure
 */
int vec0Update_InsertRowidStep(vec0_vtab *p, sqlite3_value *idValue,
                               i64 *rowid) {

  /**
   * An insert into a vec0 table can happen a few different ways:
   *  1) With default INTEGER primary key: With a supplied i64 rowid
   *  2) With default INTEGER primary key: WITHOUT a supplied rowid
   *  3) With TEXT primary key: supplied text rowid
   */

  int rc;

  // Option 3: vtab has a user-defined TEXT primary key, so ensure a text value
  // is provided.
  if (p->pkIsText) {
    if (sqlite3_value_type(idValue) != SQLITE_TEXT) {
      // IMP: V04200_21039
      vtab_set_error(&p->base,
                     "The %s virtual table was declared with a TEXT primary "
                     "key, but a non-TEXT value was provided in an INSERT.",
                     p->tableName);
      return SQLITE_ERROR;
    }

    return vec0_rowids_insert_id(p, idValue, rowid);
  }

  // Option 1: User supplied a i64 rowid
  if (sqlite3_value_type(idValue) == SQLITE_INTEGER) {
    i64 suppliedRowid = sqlite3_value_int64(idValue);
    rc = vec0_rowids_insert_rowid(p, suppliedRowid);
    if (rc == SQLITE_OK) {
      *rowid = suppliedRowid;
    }
    return rc;
  }

  // Option 2: User did not suppled a rowid

  if (sqlite3_value_type(idValue) != SQLITE_NULL) {
    // IMP: V30855_14925
    vtab_set_error(&p->base,
                   "Only integers are allowed for primary key values on %s",
                   p->tableName);
    return SQLITE_ERROR;
  }
  // NULL to get next auto-incremented value
  return vec0_rowids_insert_id(p, NULL, rowid);
}

/**
 * @brief Determines the "next available" chunk position for a newly inserted
 * vec0 row.
 *
 * This operation may insert a new "blank" chunk the _chunks table, if there is
 * no more space in previous chunks.
 *
 * @param p: virtual table
 * @param partitionKeyValues: array of partition key column values, to constrain
 * against any partition key columns.
 * @param chunk_rowid: Output rowid of the chunk in the _chunks virtual table
 * that has the avialabiity.
 * @param chunk_offset: Output the index of the available space insert the
 * chunk, based on the index of the first available validity bit.
 * @param pBlobValidity: Output blob of the validity column of the available
 * chunk. Will be opened with read/write permissions.
 * @param pValidity: Output buffer of the original chunk's validity column.
 *    Needs to be cleaned up with sqlite3_free().
 * @return int SQLITE_OK on success, error code on failure
 */
int vec0Update_InsertNextAvailableStep(
    vec0_vtab *p, sqlite3_value **partitionKeyValues, i64 *chunk_rowid,
    i64 *chunk_offset, sqlite3_blob **blobChunksValidity,
    const unsigned char **bufferChunksValidity) {

  int rc;
  i64 validitySize;
  *chunk_offset = -1;

  rc = vec0_get_latest_chunk_rowid(p, chunk_rowid, partitionKeyValues);
  if (rc == SQLITE_EMPTY) {
    goto done;
  }
  if (rc != SQLITE_OK) {
    goto cleanup;
  }

  rc = sqlite3_blob_open(p->db, p->schemaName, p->shadowChunksName, "validity",
                         *chunk_rowid, 1, blobChunksValidity);
  if (rc != SQLITE_OK) {
    // IMP: V22053_06123
    vtab_set_error(&p->base,
                   VEC_INTERAL_ERROR
                   "could not open validity blob on %s.%s.%lld",
                   p->schemaName, p->shadowChunksName, *chunk_rowid);
    goto cleanup;
  }

  validitySize = sqlite3_blob_bytes(*blobChunksValidity);
  if (validitySize != p->chunk_size / CHAR_BIT) {
    // IMP: V29362_13432
    vtab_set_error(&p->base,
                   VEC_INTERAL_ERROR
                   "validity blob size mismatch on "
                   "%s.%s.%lld, expected %lld but received %lld.",
                   p->schemaName, p->shadowChunksName, *chunk_rowid,
                   (i64)(p->chunk_size / CHAR_BIT), validitySize);
    rc = SQLITE_ERROR;
    goto cleanup;
  }

  *bufferChunksValidity = sqlite3_malloc(validitySize);
  if (!(*bufferChunksValidity)) {
    vtab_set_error(&p->base, VEC_INTERAL_ERROR
                   "Could not allocate memory for validity bitmap");
    rc = SQLITE_NOMEM;
    goto cleanup;
  }

  rc = sqlite3_blob_read(*blobChunksValidity, (void *)*bufferChunksValidity,
                         validitySize, 0);

  if (rc != SQLITE_OK) {
    vtab_set_error(&p->base,
                   VEC_INTERAL_ERROR
                   "Could not read validity bitmap for %s.%s.%lld",
                   p->schemaName, p->shadowChunksName, *chunk_rowid);
    goto cleanup;
  }

  // find the next available offset, ie first `0` in the bitmap.
  for (int i = 0; i < validitySize; i++) {
    if ((*bufferChunksValidity)[i] == 0b11111111)
      continue;
    for (int j = 0; j < CHAR_BIT; j++) {
      if (((((*bufferChunksValidity)[i] >> j) & 1) == 0)) {
        *chunk_offset = (i * CHAR_BIT) + j;
        goto done;
      }
    }
  }

done:
  // latest chunk was full, so need to create a new one
  if (*chunk_offset == -1) {
    rc = vec0_new_chunk(p, partitionKeyValues, chunk_rowid);
    if (rc != SQLITE_OK) {
      // IMP: V08441_25279
      vtab_set_error(&p->base,
                     VEC_INTERAL_ERROR "Could not insert a new vector chunk");
      rc = vec0_error_rc(rc); // otherwise raises a DatabaseError and not
                              // operational error?
      goto cleanup;
    }
    *chunk_offset = 0;

    // blobChunksValidity and pValidity are stale, pointing to the previous
    // (full) chunk. to re-assign them
    rc = sqlite3_blob_close(*blobChunksValidity);
    sqlite3_free((void *)*bufferChunksValidity);
    *blobChunksValidity = NULL;
    *bufferChunksValidity = NULL;
    if (rc != SQLITE_OK) {
      vtab_set_error(&p->base, VEC_INTERAL_ERROR
                     "unknown error, blobChunksValidity could not be closed, "
                     "please file an issue.");
      rc = SQLITE_ERROR;
      goto cleanup;
    }

    rc = sqlite3_blob_open(p->db, p->schemaName, p->shadowChunksName,
                           "validity", *chunk_rowid, 1, blobChunksValidity);
    if (rc != SQLITE_OK) {
      vtab_set_error(
          &p->base,
          VEC_INTERAL_ERROR
          "Could not open validity blob for newly created chunk %s.%s.%lld",
          p->schemaName, p->shadowChunksName, *chunk_rowid);
      goto cleanup;
    }
    validitySize = sqlite3_blob_bytes(*blobChunksValidity);
    if (validitySize != p->chunk_size / CHAR_BIT) {
      vtab_set_error(&p->base,
                     VEC_INTERAL_ERROR
                     "validity blob size mismatch for newly created chunk "
                     "%s.%s.%lld. Exepcted %lld, got %lld",
                     p->schemaName, p->shadowChunksName, *chunk_rowid,
                     p->chunk_size / CHAR_BIT, validitySize);
      goto cleanup;
    }
    *bufferChunksValidity = sqlite3_malloc(validitySize);
    if (!*bufferChunksValidity) {
      rc = SQLITE_NOMEM;
      goto cleanup;
    }
    rc = sqlite3_blob_read(*blobChunksValidity, (void *)*bufferChunksValidity,
                           validitySize, 0);
    if (rc != SQLITE_OK) {
      vtab_set_error(&p->base,
                     VEC_INTERAL_ERROR
                     "could not read validity blob newly created chunk "
                     "%s.%s.%lld",
                     p->schemaName, p->shadowChunksName, *chunk_rowid);
      goto cleanup;
    }
  }

  rc = SQLITE_OK;

cleanup:
  return rc;
}

/**
 * @brief Write the vector data into the provided vector blob at the given
 * offset
 *
 * @param blobVectors SQLite BLOB to write to
 * @param chunk_offset the "offset" (ie validity bitmap position) to write the
 * vector to
 * @param bVector pointer to the vector containing data
 * @param dimensions how many dimensions the vector has
 * @param element_type the vector type
 * @return result of sqlite3_blob_write, SQLITE_OK on success, otherwise failure
 */
static int
vec0_write_vector_to_vector_blob(sqlite3_blob *blobVectors, i64 chunk_offset,
                                 const void *bVector, size_t dimensions,
                                 enum VectorElementType element_type) {
  int n = 0;
  int offset = 0;

  switch (element_type) {
  case SQLITE_VEC_ELEMENT_TYPE_FLOAT32:
    n = dimensions * sizeof(f32);
    offset = chunk_offset * dimensions * sizeof(f32);
    break;
  case SQLITE_VEC_ELEMENT_TYPE_INT8:
    n = dimensions * sizeof(i8);
    offset = chunk_offset * dimensions * sizeof(i8);
    break;
  case SQLITE_VEC_ELEMENT_TYPE_BIT:
    n = dimensions / CHAR_BIT;
    offset = chunk_offset * dimensions / CHAR_BIT;
    break;
  default:
    return SQLITE_ERROR;
  }

  return sqlite3_blob_write(blobVectors, bVector, n, offset);
}

/**
 * @brief
 *
 * @param p vec0 virtual table
 * @param chunk_rowid: which chunk to write to
 * @param chunk_offset: the offset inside the chunk to write the vector to.
 * @param rowid: the rowid of the inserting row
 * @param vectorDatas: array of the vector data to insert
 * @param blobValidity: writeable validity blob of the row's assigned chunk.
 * @param validity: snapshot buffer of the valdity column from the row's
 * assigned chunk.
 * @return int SQLITE_OK on success, error code on failure
 */
int vec0Update_InsertWriteFinalStep(vec0_vtab *p, i64 chunk_rowid,
                                    i64 chunk_offset, i64 rowid,
                                    void *vectorDatas[],
                                    sqlite3_blob *blobChunksValidity,
                                    const unsigned char *bufferChunksValidity) {
  int rc, brc;
  sqlite3_blob *blobChunksRowids = NULL;

  // mark the validity bit for this row in the chunk's validity bitmap
  // Get the byte offset of the bitmap
  char unsigned bx = bufferChunksValidity[chunk_offset / CHAR_BIT];
  // set the bit at the chunk_offset position inside that byte
  bx = bx | (1 << (chunk_offset % CHAR_BIT));
  // write that 1 byte
  rc = sqlite3_blob_write(blobChunksValidity, &bx, 1, chunk_offset / CHAR_BIT);
  if (rc != SQLITE_OK) {
    vtab_set_error(&p->base, VEC_INTERAL_ERROR "could not mark validity bit ");
    return rc;
  }

  // Go insert the vector data into the vector chunk shadow tables
  for (int i = 0; i < p->numVectorColumns; i++) {
    sqlite3_blob *blobVectors;
    rc = sqlite3_blob_open(p->db, p->schemaName, p->shadowVectorChunksNames[i],
                           "vectors", chunk_rowid, 1, &blobVectors);
    if (rc != SQLITE_OK) {
      vtab_set_error(&p->base, "Error opening vector blob at %s.%s.%lld",
                     p->schemaName, p->shadowVectorChunksNames[i], chunk_rowid);
      goto cleanup;
    }

    i64 expected =
        p->chunk_size * vector_column_byte_size(p->vector_columns[i]);
    i64 actual = sqlite3_blob_bytes(blobVectors);

    if (actual != expected) {
      // IMP: V16386_00456
      vtab_set_error(
          &p->base,
          VEC_INTERAL_ERROR
          "vector blob size mismatch on %s.%s.%lld. Expected %lld, actual %lld",
          p->schemaName, p->shadowVectorChunksNames[i], chunk_rowid, expected,
          actual);
      rc = SQLITE_ERROR;
      // already error, can ignore result code
      sqlite3_blob_close(blobVectors);
      goto cleanup;
    };

    rc = vec0_write_vector_to_vector_blob(
        blobVectors, chunk_offset, vectorDatas[i],
        p->vector_columns[i].dimensions, p->vector_columns[i].element_type);
    if (rc != SQLITE_OK) {
      vtab_set_error(&p->base,
                     VEC_INTERAL_ERROR
                     "could not write vector blob on %s.%s.%lld",
                     p->schemaName, p->shadowVectorChunksNames[i], chunk_rowid);
      rc = SQLITE_ERROR;
      // already error, can ignore result code
      sqlite3_blob_close(blobVectors);
      goto cleanup;
    }
    rc = sqlite3_blob_close(blobVectors);
    if (rc != SQLITE_OK) {
      vtab_set_error(&p->base,
                     VEC_INTERAL_ERROR
                     "could not close vector blob on %s.%s.%lld",
                     p->schemaName, p->shadowVectorChunksNames[i], chunk_rowid);
      rc = SQLITE_ERROR;
      goto cleanup;
    }
  }

  // write the new rowid to the rowids column of the _chunks table
  rc = sqlite3_blob_open(p->db, p->schemaName, p->shadowChunksName, "rowids",
                         chunk_rowid, 1, &blobChunksRowids);
  if (rc != SQLITE_OK) {
    // IMP: V09221_26060
    vtab_set_error(&p->base,
                   VEC_INTERAL_ERROR "could not open rowids blob on %s.%s.%lld",
                   p->schemaName, p->shadowChunksName, chunk_rowid);
    goto cleanup;
  }
  i64 expected = p->chunk_size * sizeof(i64);
  i64 actual = sqlite3_blob_bytes(blobChunksRowids);
  if (expected != actual) {
    // IMP: V12779_29618
    vtab_set_error(
        &p->base,
        VEC_INTERAL_ERROR
        "rowids blob size mismatch on %s.%s.%lld. Expected %lld, actual %lld",
        p->schemaName, p->shadowChunksName, chunk_rowid, expected, actual);
    rc = SQLITE_ERROR;
    goto cleanup;
  }
  rc = sqlite3_blob_write(blobChunksRowids, &rowid, sizeof(i64),
                          chunk_offset * sizeof(i64));
  if (rc != SQLITE_OK) {
    vtab_set_error(
        &p->base, VEC_INTERAL_ERROR "could not write rowids blob on %s.%s.%lld",
        p->schemaName, p->shadowChunksName, chunk_rowid);
    rc = SQLITE_ERROR;
    goto cleanup;
  }

  // Now with all the vectors inserted, go back and update the _rowids table
  // with the new chunk_rowid/chunk_offset values
  rc = vec0_rowids_update_position(p, rowid, chunk_rowid, chunk_offset);

cleanup:
  brc = sqlite3_blob_close(blobChunksRowids);
  if ((rc == SQLITE_OK) && (brc != SQLITE_OK)) {
    vtab_set_error(
        &p->base, VEC_INTERAL_ERROR "could not close rowids blob on %s.%s.%lld",
        p->schemaName, p->shadowChunksName, chunk_rowid);
    return brc;
  }
  return rc;
}

/**
 * @brief Execute a metadata text SQL statement (INSERT/UPDATE/DELETE).
 *
 * This helper handles the prepare→bind→step→finalize→free pattern for
 * metadata text data operations. Takes ownership of zSql and frees it.
 *
 * @param db SQLite database connection
 * @param zSql SQL string allocated by sqlite3_mprintf (will be freed)
 * @param rowid Row ID to bind to parameter 1
 * @param text Text data to bind to parameter 2, or NULL for DELETE
 * @param text_len Length of text data (ignored if text is NULL)
 * @return SQLITE_OK on success, error code on failure
 */
static int vec0_exec_metadata_text_sql(sqlite3 *db, char *zSql, i64 rowid,
                                       const char *text, int text_len) {
  sqlite3_stmt *stmt;
  int rc = sqlite3_prepare_v2(db, zSql, -1, &stmt, NULL);
  if (rc != SQLITE_OK) {
    sqlite3_free(zSql);
    return rc;
  }
  sqlite3_bind_int64(stmt, 1, rowid);
  if (text) {
    sqlite3_bind_text(stmt, 2, text, text_len, SQLITE_STATIC);
  }
  rc = sqlite3_step(stmt);
  sqlite3_finalize(stmt);
  sqlite3_free(zSql);

  return (rc == SQLITE_DONE) ? SQLITE_OK : vec0_error_rc(rc);
}

// Checks that v has the type of the given metadata column, setting a vtab
// error if not.
static int vec0_validate_metadata_value(vec0_vtab *p, int metadata_column_idx,
                                        sqlite3_value *v) {
  struct Vec0MetadataColumnDefinition *metadata_column =
      &p->metadata_columns[metadata_column_idx];
  switch (metadata_column->kind) {
  case VEC0_METADATA_COLUMN_KIND_BOOLEAN: {
    if (sqlite3_value_type(v) != SQLITE_INTEGER ||
        ((sqlite3_value_int64(v) != 0) && (sqlite3_value_int64(v) != 1))) {
      vtab_set_error(&p->base,
                     "Expected 0 or 1 for BOOLEAN metadata column %.*s",
                     metadata_column->name_length, metadata_column->name);
      return SQLITE_ERROR;
    }
    break;
  }
  case VEC0_METADATA_COLUMN_KIND_INTEGER: {
    if (sqlite3_value_type(v) != SQLITE_INTEGER) {
      vtab_set_error(
          &p->base,
          "Expected integer for INTEGER metadata column %.*s, received %s",
          metadata_column->name_length, metadata_column->name,
          type_name(sqlite3_value_type(v)));
      return SQLITE_ERROR;
    }
    break;
  }
  case VEC0_METADATA_COLUMN_KIND_FLOAT: {
    if (sqlite3_value_type(v) != SQLITE_FLOAT) {
      vtab_set_error(
          &p->base,
          "Expected float for FLOAT metadata column %.*s, received %s",
          metadata_column->name_length, metadata_column->name,
          type_name(sqlite3_value_type(v)));
      return SQLITE_ERROR;
    }
    break;
  }
  case VEC0_METADATA_COLUMN_KIND_TEXT: {
    if (sqlite3_value_type(v) != SQLITE_TEXT) {
      vtab_set_error(&p->base,
                     "Expected text for TEXT metadata column %.*s, received %s",
                     metadata_column->name_length, metadata_column->name,
                     type_name(sqlite3_value_type(v)));
      return SQLITE_ERROR;
    }
    break;
  }
  }
  return SQLITE_OK;
}

int vec0_write_metadata_value(vec0_vtab *p, int metadata_column_idx, i64 rowid,
                              i64 chunk_id, i64 chunk_offset, sqlite3_value *v,
                              int isupdate) {
  sqlite3_blob *blobValue = NULL;
  vec0_metadata_column_kind kind =
      p->metadata_columns[metadata_column_idx].kind;
  int rc = vec0_validate_metadata_value(p, metadata_column_idx, v);
  if (rc != SQLITE_OK) {
    return rc;
  }

  rc = sqlite3_blob_open(p->db, p->schemaName,
                         p->shadowMetadataChunksNames[metadata_column_idx],
                         "data", chunk_id, 1, &blobValue);
  if (rc != SQLITE_OK) {
    goto done;
  }

  switch (kind) {
  case VEC0_METADATA_COLUMN_KIND_BOOLEAN: {
    u8 block;
    int value = sqlite3_value_int(v);
    rc = sqlite3_blob_read(blobValue, &block, sizeof(u8),
                           (int)(chunk_offset / CHAR_BIT));
    if (rc != SQLITE_OK) {
      goto done;
    }

    if (value) {
      block |= 1 << (chunk_offset % CHAR_BIT);
    } else {
      block &= ~(1 << (chunk_offset % CHAR_BIT));
    }

    rc = sqlite3_blob_write(blobValue, &block, sizeof(u8),
                            chunk_offset / CHAR_BIT);
    break;
  }
  case VEC0_METADATA_COLUMN_KIND_INTEGER: {
    i64 value = sqlite3_value_int64(v);
    rc = sqlite3_blob_write(blobValue, &value, sizeof(value),
                            chunk_offset * sizeof(i64));
    break;
  }
  case VEC0_METADATA_COLUMN_KIND_FLOAT: {
    double value = sqlite3_value_double(v);
    rc = sqlite3_blob_write(blobValue, &value, sizeof(value),
                            chunk_offset * sizeof(double));
    break;
  }
  case VEC0_METADATA_COLUMN_KIND_TEXT: {
    int prev_n;
    rc =
        sqlite3_blob_read(blobValue, &prev_n, sizeof(int),
                          chunk_offset * VEC0_METADATA_TEXT_VIEW_BUFFER_LENGTH);
    if (rc != SQLITE_OK) {
      goto done;
    }

    const char *s = (const char *)sqlite3_value_text(v);
    int n = sqlite3_value_bytes(v);
    u8 view[VEC0_METADATA_TEXT_VIEW_BUFFER_LENGTH];
    memset(view, 0, VEC0_METADATA_TEXT_VIEW_BUFFER_LENGTH);
    memcpy(view, &n, sizeof(int));
    memcpy(view + 4, s, min(n, VEC0_METADATA_TEXT_VIEW_BUFFER_LENGTH - 4));

    rc = sqlite3_blob_write(
        blobValue, &view, VEC0_METADATA_TEXT_VIEW_BUFFER_LENGTH,
        chunk_offset * VEC0_METADATA_TEXT_VIEW_BUFFER_LENGTH);
    if (rc != SQLITE_OK) {
      goto done;
    }
    if (n > VEC0_METADATA_TEXT_VIEW_DATA_LENGTH) {
      char *zSql;
      if (isupdate && (prev_n > VEC0_METADATA_TEXT_VIEW_DATA_LENGTH)) {
        zSql =
            sqlite3_mprintf("UPDATE " VEC0_SHADOW_METADATA_TEXT_DATA_NAME
                            " SET data = ?2 WHERE rowid = ?1",
                            p->schemaName, p->tableName, metadata_column_idx);
      } else {
        zSql =
            sqlite3_mprintf("INSERT INTO " VEC0_SHADOW_METADATA_TEXT_DATA_NAME
                            " (rowid, data) VALUES (?1, ?2)",
                            p->schemaName, p->tableName, metadata_column_idx);
      }
      if (!zSql) {
        rc = SQLITE_NOMEM;
        goto done;
      }
      rc = vec0_exec_metadata_text_sql(p->db, zSql, rowid, s, n);
      if (rc != SQLITE_OK) {
        goto done;
      }
    } else if (prev_n > VEC0_METADATA_TEXT_VIEW_DATA_LENGTH) {
      char *zSql = sqlite3_mprintf(
          "DELETE FROM " VEC0_SHADOW_METADATA_TEXT_DATA_NAME " WHERE rowid = ?",
          p->schemaName, p->tableName, metadata_column_idx);
      if (!zSql) {
        rc = SQLITE_NOMEM;
        goto done;
      }
      rc = vec0_exec_metadata_text_sql(p->db, zSql, rowid, NULL, 0);
      if (rc != SQLITE_OK) {
        goto done;
      }
    }
    break;
  }
  }

done:
  if (blobValue) {
    int closeRc = sqlite3_blob_close(blobValue);
    if (rc == SQLITE_OK) {
      rc = closeRc;
    }
  }
  return rc;
}

// INSERT OR REPLACE deletes the existing row through vec0Update_Delete.
int vec0Update_Delete(sqlite3_vtab *pVTab, sqlite3_value *idValue);

/**
 * @brief Handles INSERT INTO operations on a vec0 table.
 *
 * @return int SQLITE_OK on success, otherwise error code on failure
 */
int vec0Update_Insert(sqlite3_vtab *pVTab, int argc, sqlite3_value **argv,
                      sqlite_int64 *pRowid) {
  UNUSED_PARAMETER(argc);
  vec0_vtab *p = (vec0_vtab *)pVTab;
  int rc;
  // Rowid for the inserted row, deterimined by the inserted ID + _rowids shadow
  // table
  i64 rowid;

  // Array to hold the vector data of the inserted row. Individual elements will
  // have a lifetime bound to the argv[..] values.
  void *vectorDatas[VEC0_MAX_VECTOR_COLUMNS];
  // Array to hold cleanup functions for vectorDatas[]
  vector_cleanup cleanups[VEC0_MAX_VECTOR_COLUMNS];
  memset(
      cleanups, 0,
      sizeof(
          cleanups)); // NOLINT(bugprone-multi-level-implicit-pointer-conversion)

  sqlite3_value *partitionKeyValues[VEC0_MAX_PARTITION_COLUMNS];

  // Rowid of the chunk in the _chunks shadow table that the row will be a part
  // of.
  i64 chunk_rowid;
  // offset within the chunk where the rowid belongs
  i64 chunk_offset;

  // a write-able blob of the validity column for the given chunk. Used to mark
  // validity bit
  sqlite3_blob *blobChunksValidity = NULL;
  // buffer for the valididty column for the given chunk. Maybe not needed here?
  const unsigned char *bufferChunksValidity = NULL;
  int numReadVectors = 0;

  // Read all provided partition key values into partitionKeyValues
  for (int i = 0; i < vec0_num_defined_user_columns(p); i++) {
    if (p->user_column_kinds[i] != SQLITE_VEC0_USER_COLUMN_KIND_PARTITION) {
      continue;
    }
    int partition_key_idx = p->user_column_idxs[i];
    partitionKeyValues[partition_key_idx] =
        argv[2 + VEC0_COLUMN_USERN_START + i];

    int new_value_type =
        sqlite3_value_type(partitionKeyValues[partition_key_idx]);
    if ((new_value_type != SQLITE_NULL) &&
        (new_value_type != p->paritition_columns[partition_key_idx].type)) {
      // IMP: V11454_28292
      vtab_set_error(pVTab,
                     "Partition key type mismatch: The partition key column "
                     "%.*s has type %s, but %s was provided.",
                     p->paritition_columns[partition_key_idx].name_length,
                     p->paritition_columns[partition_key_idx].name,
                     type_name(p->paritition_columns[partition_key_idx].type),
                     type_name(new_value_type));
      rc = SQLITE_ERROR;
      goto cleanup;
    }
  }

  // read all the inserted vectors  into vectorDatas, validate their lengths.
  for (int i = 0; i < vec0_num_defined_user_columns(p); i++) {
    if (p->user_column_kinds[i] != SQLITE_VEC0_USER_COLUMN_KIND_VECTOR) {
      continue;
    }
    int vector_column_idx = p->user_column_idxs[i];
    sqlite3_value *valueVector = argv[2 + VEC0_COLUMN_USERN_START + i];
    size_t dimensions;

    char *pzError;
    enum VectorElementType elementType;
    rc = vector_from_value(valueVector, &vectorDatas[vector_column_idx],
                           &dimensions, &elementType,
                           &cleanups[vector_column_idx], &pzError);
    if (rc != SQLITE_OK) {
      // IMP: V06519_23358
      vtab_set_error(pVTab,
                     "Inserted vector for the \"%.*s\" column is invalid: %z",
                     p->vector_columns[vector_column_idx].name_length,
                     p->vector_columns[vector_column_idx].name, pzError);
      rc = SQLITE_ERROR;
      goto cleanup;
    }

    numReadVectors++;
    if (elementType != p->vector_columns[vector_column_idx].element_type) {
      // IMP: V08221_25059
      vtab_set_error(
          pVTab,
          "Inserted vector for the \"%.*s\" column is expected to be of type "
          "%s, but a %s vector was provided.",
          p->vector_columns[i].name_length, p->vector_columns[i].name,
          vector_subtype_name(p->vector_columns[i].element_type),
          vector_subtype_name(elementType));
      rc = SQLITE_ERROR;
      goto cleanup;
    }

    if (dimensions != p->vector_columns[vector_column_idx].dimensions) {
      // IMP: V01145_17984
      vtab_set_error(
          pVTab,
          "Dimension mismatch for inserted vector for the \"%.*s\" column. "
          "Expected %d dimensions but received %d.",
          p->vector_columns[vector_column_idx].name_length,
          p->vector_columns[vector_column_idx].name,
          p->vector_columns[vector_column_idx].dimensions, dimensions);
      rc = SQLITE_ERROR;
      goto cleanup;
    }
  }

  // Cannot insert a value in the hidden "distance" column
  if (sqlite3_value_type(argv[2 + vec0_column_distance_idx(p)]) !=
      SQLITE_NULL) {
    // IMP: V24228_08298
    vtab_set_error(pVTab,
                   "A value was provided for the hidden \"distance\" column.");
    rc = SQLITE_ERROR;
    goto cleanup;
  }
  // Cannot insert a value in the hidden "k" column
  if (sqlite3_value_type(argv[2 + vec0_column_k_idx(p)]) != SQLITE_NULL) {
    // IMP: V11875_28713
    vtab_set_error(pVTab, "A value was provided for the hidden \"k\" column.");
    rc = SQLITE_ERROR;
    goto cleanup;
  }
  // Cannot insert a value in the hidden "mmr_lambda" column
  if (sqlite3_value_type(argv[2 + vec0_column_mmr_lambda_idx(p)]) !=
      SQLITE_NULL) {
    vtab_set_error(
        pVTab, "A value was provided for the hidden \"mmr_lambda\" column.");
    rc = SQLITE_ERROR;
    goto cleanup;
  }

  // Check auxiliary and metadata value types before the first write: the
  // shadow-table writes below are not rolled back if the INSERT fails.
  for (int i = 0; i < vec0_num_defined_user_columns(p); i++) {
    sqlite3_value *v = argv[2 + VEC0_COLUMN_USERN_START + i];
    if (p->user_column_kinds[i] == SQLITE_VEC0_USER_COLUMN_KIND_AUXILIARY) {
      int auxiliary_key_idx = p->user_column_idxs[i];
      int v_type = sqlite3_value_type(v);
      if (v_type != SQLITE_NULL &&
          (v_type != p->auxiliary_columns[auxiliary_key_idx].type)) {
        rc = SQLITE_CONSTRAINT;
        vtab_set_error(pVTab,
                       "Auxiliary column type mismatch: The auxiliary column "
                       "%.*s has type %s, but %s was provided.",
                       p->auxiliary_columns[auxiliary_key_idx].name_length,
                       p->auxiliary_columns[auxiliary_key_idx].name,
                       type_name(p->auxiliary_columns[auxiliary_key_idx].type),
                       type_name(v_type));
        goto cleanup;
      }
    } else if (p->user_column_kinds[i] ==
               SQLITE_VEC0_USER_COLUMN_KIND_METADATA) {
      rc = vec0_validate_metadata_value(p, p->user_column_idxs[i], v);
      if (rc != SQLITE_OK) {
        goto cleanup;
      }
    }
  }

  // Handle INSERT OR REPLACE: if the conflict resolution is REPLACE and the
  // row already exists, delete the existing row first before inserting.
  if (sqlite3_vtab_on_conflict(p->db) == SQLITE_REPLACE) {
    sqlite3_value *idValue = argv[2 + VEC0_COLUMN_ID];
    int idType = sqlite3_value_type(idValue);
    int existingRowExists = 0;

    if (p->pkIsText && idType == SQLITE_TEXT) {
      i64 existingRowid;
      rc = vec0_rowid_from_id(p, idValue, &existingRowid);
      if (rc == SQLITE_OK) {
        existingRowExists = 1;
      } else if (rc == SQLITE_EMPTY) {
        rc = SQLITE_OK; // row doesn't exist, proceed with normal insert
      } else {
        goto cleanup;
      }
    } else if (!p->pkIsText && idType == SQLITE_INTEGER) {
      i64 existingRowid = sqlite3_value_int64(idValue);
      i64 chunk_id_tmp, chunk_offset_tmp;
      rc = vec0_get_chunk_position(p, existingRowid, NULL, &chunk_id_tmp,
                                   &chunk_offset_tmp);
      if (rc == SQLITE_OK) {
        existingRowExists = 1;
      } else if (rc == SQLITE_EMPTY) {
        rc = SQLITE_OK; // row doesn't exist, proceed with normal insert
      } else {
        goto cleanup;
      }
    }

    if (existingRowExists) {
      rc = vec0Update_Delete(pVTab, idValue);
      if (rc != SQLITE_OK) {
        goto cleanup;
      }
    }
  }

  // Step #1: Insert/get a rowid for this row, from the _rowids table.
  rc = vec0Update_InsertRowidStep(p, argv[2 + VEC0_COLUMN_ID], &rowid);
  if (rc != SQLITE_OK) {
    goto cleanup;
  }

  // Step #2: Find the next "available" position in the _chunks table for this
  // row.
  rc = vec0Update_InsertNextAvailableStep(p, partitionKeyValues, &chunk_rowid,
                                          &chunk_offset, &blobChunksValidity,
                                          &bufferChunksValidity);
  if (rc != SQLITE_OK) {
    goto cleanup;
  }

  // Step #3: With the next available chunk position, write out all the vectors
  //          to their specified location.
  rc = vec0Update_InsertWriteFinalStep(p, chunk_rowid, chunk_offset, rowid,
                                       vectorDatas, blobChunksValidity,
                                       bufferChunksValidity);
  if (rc != SQLITE_OK) {
    goto cleanup;
  }

  if (p->numAuxiliaryColumns > 0) {
    sqlite3_stmt *stmt;
    sqlite3_str *s = sqlite3_str_new(NULL);
    sqlite3_str_appendf(s, "INSERT INTO " VEC0_SHADOW_AUXILIARY_NAME "(rowid ",
                        p->schemaName, p->tableName);
    for (int i = 0; i < p->numAuxiliaryColumns; i++) {
      sqlite3_str_appendf(s, ", value%02d", i);
    }
    sqlite3_str_appendall(s, ") VALUES (? ");
    for (int i = 0; i < p->numAuxiliaryColumns; i++) {
      sqlite3_str_appendall(s, ", ?");
    }
    sqlite3_str_appendall(s, ")");
    char *zSql = sqlite3_str_finish(s);
    if (!zSql) {
      rc = SQLITE_NOMEM;
      goto cleanup;
    }
    rc = sqlite3_prepare_v2(p->db, zSql, -1, &stmt, NULL);
    sqlite3_free(zSql);
    if (rc != SQLITE_OK) {
      goto cleanup;
    }
    sqlite3_bind_int64(stmt, 1, rowid);

    for (int i = 0; i < vec0_num_defined_user_columns(p); i++) {
      if (p->user_column_kinds[i] != SQLITE_VEC0_USER_COLUMN_KIND_AUXILIARY) {
        continue;
      }
      int auxiliary_key_idx = p->user_column_idxs[i];
      sqlite3_value *v = argv[2 + VEC0_COLUMN_USERN_START + i];
      // first 1 is for 1-based indexing on sqlite3_bind_*, second 1 is to
      // account for initial rowid parameter
      sqlite3_bind_value(stmt, 1 + 1 + auxiliary_key_idx, v);
    }

    rc = sqlite3_step(stmt);
    if (rc != SQLITE_DONE) {
      sqlite3_finalize(stmt);
      rc = vec0_error_rc(rc);
      goto cleanup;
    }
    sqlite3_finalize(stmt);
  }

  for (int i = 0; i < vec0_num_defined_user_columns(p); i++) {
    if (p->user_column_kinds[i] != SQLITE_VEC0_USER_COLUMN_KIND_METADATA) {
      continue;
    }
    int metadata_idx = p->user_column_idxs[i];
    sqlite3_value *v = argv[2 + VEC0_COLUMN_USERN_START + i];
    rc = vec0_write_metadata_value(p, metadata_idx, rowid, chunk_rowid,
                                   chunk_offset, v, 0);
    if (rc != SQLITE_OK) {
      goto cleanup;
    }
  }

  *pRowid = rowid;
  rc = SQLITE_OK;

cleanup:
  for (int i = 0; i < numReadVectors; i++) {
    if (cleanups[i]) {
      cleanups[i](vectorDatas[i]);
    }
  }
  sqlite3_free((void *)bufferChunksValidity);
  int brc = sqlite3_blob_close(blobChunksValidity);
  if ((rc == SQLITE_OK) && (brc != SQLITE_OK)) {
    vtab_set_error(&p->base,
                   VEC_INTERAL_ERROR "unknown error, blobChunksValidity could "
                                     "not be closed, please file an issue");
    return brc;
  }
  return rc;
}

// Clears the row's validity bit, and sets *chunkEmpty to whether that was the
// chunk's last set bit.
int vec0Update_Delete_ClearValidity(vec0_vtab *p, i64 chunk_id,
                                    u64 chunk_offset, int *chunkEmpty) {
  int rc, brc;
  sqlite3_blob *blobChunksValidity = NULL;
  char unsigned bx;
  int validityOffset = chunk_offset / CHAR_BIT;

  // 2. ensure chunks.validity bit is 1, then set to 0
  rc = sqlite3_blob_open(p->db, p->schemaName, p->shadowChunksName, "validity",
                         chunk_id, 1, &blobChunksValidity);
  if (rc != SQLITE_OK) {
    // IMP: V26002_10073
    vtab_set_error(&p->base, "could not open validity blob for %s.%s.%lld",
                   p->schemaName, p->shadowChunksName, chunk_id);
    return vec0_error_rc(rc);
  }
  // will skip the sqlite3_blob_bytes(blobChunksValidity) check for now,
  // the read below would catch it

  rc = sqlite3_blob_read(blobChunksValidity, &bx, sizeof(bx), validityOffset);
  if (rc != SQLITE_OK) {
    // IMP: V21193_05263
    vtab_set_error(
        &p->base, "could not read validity blob for %s.%s.%lld at %d",
        p->schemaName, p->shadowChunksName, chunk_id, validityOffset);
    goto cleanup;
  }
  if (!((bx >> (chunk_offset % CHAR_BIT)) & 1)) {
    // IMP: V21193_05263
    rc = SQLITE_ERROR;
    vtab_set_error(
        &p->base,
        "vec0 deletion error: validity bit is not set for %s.%s.%lld at %d",
        p->schemaName, p->shadowChunksName, chunk_id, validityOffset);
    goto cleanup;
  }
  char unsigned mask = ~(1 << (chunk_offset % CHAR_BIT));
  char result = bx & mask;
  rc = sqlite3_blob_write(blobChunksValidity, &result, sizeof(bx),
                          validityOffset);
  if (rc != SQLITE_OK) {
    vtab_set_error(
        &p->base, "could not write to validity blob for %s.%s.%lld at %d",
        p->schemaName, p->shadowChunksName, chunk_id, validityOffset);
    goto cleanup;
  }

  // Another set bit in this byte keeps the chunk, as it does for most deletes,
  // so the rest of the bitmap is read only once this byte is zero.
  *chunkEmpty = 0;
  if (result == 0) {
    int validitySize = sqlite3_blob_bytes(blobChunksValidity);
    u8 *validity = sqlite3_malloc(validitySize);
    if (!validity) {
      rc = SQLITE_NOMEM;
      goto cleanup;
    }
    rc = sqlite3_blob_read(blobChunksValidity, validity, validitySize, 0);
    if (rc == SQLITE_OK) {
      *chunkEmpty = !bitmap_any(validity, validitySize * CHAR_BIT);
    } else {
      vtab_set_error(&p->base, "could not read validity blob for %s.%s.%lld",
                     p->schemaName, p->shadowChunksName, chunk_id);
    }
    sqlite3_free(validity);
  }

cleanup:

  brc = sqlite3_blob_close(blobChunksValidity);
  if (rc != SQLITE_OK)
    return rc;
  if (brc != SQLITE_OK) {
    vtab_set_error(&p->base,
                   "vec0 deletion error: Error commiting validity blob "
                   "transaction on %s.%s.%lld at %d",
                   p->schemaName, p->shadowChunksName, chunk_id,
                   validityOffset);
    return brc;
  }
  return SQLITE_OK;
}

int vec0Update_Delete_DeleteRowids(vec0_vtab *p, i64 rowid) {
  int rc;
  sqlite3_stmt *stmt = NULL;

  char *zSql =
      sqlite3_mprintf("DELETE FROM " VEC0_SHADOW_ROWIDS_NAME " WHERE rowid = ?",
                      p->schemaName, p->tableName);
  if (!zSql) {
    return SQLITE_NOMEM;
  }

  rc = sqlite3_prepare_v2(p->db, zSql, -1, &stmt, NULL);
  sqlite3_free(zSql);
  if (rc != SQLITE_OK) {
    goto cleanup;
  }
  sqlite3_bind_int64(stmt, 1, rowid);
  rc = sqlite3_step(stmt);
  if (rc != SQLITE_DONE) {
    goto cleanup;
  }
  rc = SQLITE_OK;

cleanup:
  sqlite3_finalize(stmt);
  return rc;
}

// Clear the rowid slot in v_chunks.rowids for the given chunk/offset
int vec0Update_Delete_ClearRowid(vec0_vtab *p, i64 chunk_id, i64 chunk_offset) {
  int rc;
  sqlite3_blob *blobChunksRowids = NULL;

  rc = sqlite3_blob_open(p->db, p->schemaName, p->shadowChunksName, "rowids",
                         chunk_id, 1, &blobChunksRowids);
  if (rc != SQLITE_OK) {
    vtab_set_error(&p->base, "could not open rowids blob for %s.%s.%lld",
                   p->schemaName, p->shadowChunksName, chunk_id);
    return vec0_error_rc(rc);
  }

  i64 expected = p->chunk_size * sizeof(i64);
  i64 actual = sqlite3_blob_bytes(blobChunksRowids);
  if (expected != actual) {
    vtab_set_error(
        &p->base,
        VEC_INTERAL_ERROR
        "rowids blob size mismatch on %s.%s.%lld. Expected %lld, actual %lld",
        p->schemaName, p->shadowChunksName, chunk_id, expected, actual);
    sqlite3_blob_close(blobChunksRowids);
    return SQLITE_ERROR;
  }

  i64 zero = 0;
  rc = sqlite3_blob_write(blobChunksRowids, &zero, sizeof(i64),
                          chunk_offset * sizeof(i64));
  int brc = sqlite3_blob_close(blobChunksRowids);
  if (rc != SQLITE_OK) {
    vtab_set_error(&p->base, "could not write rowids blob on %s.%s.%lld",
                   p->schemaName, p->shadowChunksName, chunk_id);
    return rc;
  }
  if (brc != SQLITE_OK) {
    vtab_set_error(&p->base, "could not close rowids blob on %s.%s.%lld",
                   p->schemaName, p->shadowChunksName, chunk_id);
    return brc;
  }
  return SQLITE_OK;
}

// Clear the vector bytes for each vector column at the given chunk/offset
int vec0Update_Delete_ClearVectors(vec0_vtab *p, i64 chunk_id,
                                   i64 chunk_offset) {
  for (int i = 0; i < p->numVectorColumns; i++) {
    int rc;
    sqlite3_blob *blobVectors = NULL;

    rc = sqlite3_blob_open(p->db, p->schemaName, p->shadowVectorChunksNames[i],
                           "vectors", chunk_id, 1, &blobVectors);
    if (rc != SQLITE_OK) {
      vtab_set_error(&p->base, "Could not open vectors blob for %s.%s.%lld",
                     p->schemaName, p->shadowVectorChunksNames[i], chunk_id);
      return rc;
    }

    i64 expected =
        p->chunk_size * vector_column_byte_size(p->vector_columns[i]);
    i64 actual = sqlite3_blob_bytes(blobVectors);
    if (expected != actual) {
      vtab_set_error(
          &p->base,
          VEC_INTERAL_ERROR
          "vector blob size mismatch on %s.%s.%lld. Expected %lld, actual %lld",
          p->schemaName, p->shadowVectorChunksNames[i], chunk_id, expected,
          actual);
      sqlite3_blob_close(blobVectors);
      return SQLITE_ERROR;
    }

    size_t nbytes = vector_column_byte_size(p->vector_columns[i]);
    void *zeros = sqlite3_malloc(nbytes);
    if (!zeros) {
      sqlite3_blob_close(blobVectors);
      return SQLITE_NOMEM;
    }
    memset(zeros, 0, nbytes);
    rc = vec0_write_vector_to_vector_blob(blobVectors, chunk_offset, zeros,
                                          p->vector_columns[i].dimensions,
                                          p->vector_columns[i].element_type);
    sqlite3_free(zeros);

    int brc = sqlite3_blob_close(blobVectors);
    if (rc != SQLITE_OK) {
      vtab_set_error(&p->base, "Could not write to vectors blob for %s.%s.%lld",
                     p->schemaName, p->shadowVectorChunksNames[i], chunk_id);
      return rc;
    }
    if (brc != SQLITE_OK) {
      vtab_set_error(
          &p->base,
          "Could not commit blob transaction for vectors blob for %s.%s.%lld",
          p->schemaName, p->shadowVectorChunksNames[i], chunk_id);
      return brc;
    }
  }
  return SQLITE_OK;
}

int vec0Update_Delete_DeleteAux(vec0_vtab *p, i64 rowid) {
  int rc;
  sqlite3_stmt *stmt = NULL;

  char *zSql = sqlite3_mprintf("DELETE FROM " VEC0_SHADOW_AUXILIARY_NAME
                               " WHERE rowid = ?",
                               p->schemaName, p->tableName);
  if (!zSql) {
    return SQLITE_NOMEM;
  }

  rc = sqlite3_prepare_v2(p->db, zSql, -1, &stmt, NULL);
  sqlite3_free(zSql);
  if (rc != SQLITE_OK) {
    goto cleanup;
  }
  sqlite3_bind_int64(stmt, 1, rowid);
  rc = sqlite3_step(stmt);
  if (rc != SQLITE_DONE) {
    goto cleanup;
  }
  rc = SQLITE_OK;

cleanup:
  sqlite3_finalize(stmt);
  return rc;
}

int vec0Update_Delete_ClearMetadata(vec0_vtab *p, int metadata_idx, i64 rowid,
                                    i64 chunk_id, u64 chunk_offset) {
  int rc;
  sqlite3_blob *blobValue;
  vec0_metadata_column_kind kind = p->metadata_columns[metadata_idx].kind;
  rc = sqlite3_blob_open(p->db, p->schemaName,
                         p->shadowMetadataChunksNames[metadata_idx], "data",
                         chunk_id, 1, &blobValue);
  if (rc != SQLITE_OK) {
    return rc;
  }

  switch (kind) {
  case VEC0_METADATA_COLUMN_KIND_BOOLEAN: {
    u8 block;
    rc = sqlite3_blob_read(blobValue, &block, sizeof(u8),
                           (int)(chunk_offset / CHAR_BIT));
    if (rc != SQLITE_OK) {
      goto done;
    }

    block &= ~(1 << (chunk_offset % CHAR_BIT));
    rc = sqlite3_blob_write(blobValue, &block, sizeof(u8),
                            chunk_offset / CHAR_BIT);
    break;
  }
  case VEC0_METADATA_COLUMN_KIND_INTEGER: {
    i64 v = 0;
    rc = sqlite3_blob_write(blobValue, &v, sizeof(v),
                            chunk_offset * sizeof(i64));
    break;
  }
  case VEC0_METADATA_COLUMN_KIND_FLOAT: {
    double v = 0;
    rc = sqlite3_blob_write(blobValue, &v, sizeof(v),
                            chunk_offset * sizeof(double));
    break;
  }
  case VEC0_METADATA_COLUMN_KIND_TEXT: {
    int n;
    rc =
        sqlite3_blob_read(blobValue, &n, sizeof(int),
                          chunk_offset * VEC0_METADATA_TEXT_VIEW_BUFFER_LENGTH);
    if (rc != SQLITE_OK) {
      goto done;
    }

    u8 view[VEC0_METADATA_TEXT_VIEW_BUFFER_LENGTH];
    memset(view, 0, VEC0_METADATA_TEXT_VIEW_BUFFER_LENGTH);
    rc = sqlite3_blob_write(blobValue, &view, sizeof(view),
                            chunk_offset *
                                VEC0_METADATA_TEXT_VIEW_BUFFER_LENGTH);
    if (rc != SQLITE_OK) {
      goto done;
    }

    if (n > VEC0_METADATA_TEXT_VIEW_DATA_LENGTH) {
      char *zSql = sqlite3_mprintf(
          "DELETE FROM " VEC0_SHADOW_METADATA_TEXT_DATA_NAME " WHERE rowid = ?",
          p->schemaName, p->tableName, metadata_idx);
      if (!zSql) {
        rc = SQLITE_NOMEM;
        goto done;
      }
      rc = vec0_exec_metadata_text_sql(p->db, zSql, rowid, NULL, 0);
      if (rc != SQLITE_OK) {
        goto done;
      }
    }
    break;
  }
  }
  int rc2;
done:
  rc2 = sqlite3_blob_close(blobValue);
  if (rc == SQLITE_OK) {
    return rc2;
  }
  return rc;
}

// Once a DELETE has cleared the last validity bit of its chunk, delete the
// chunk's rows from _chunks, _vector_chunksNN and _metadatachunksNN, so their
// pages are free without an optimize.
// https://github.com/asg017/sqlite-vec/commit/cb147c8
int vec0Update_Delete_DeleteChunk(vec0_vtab *p, i64 chunk_id) {
  int rc;
  sqlite3_stmt *stmt = NULL;
  char *zSql;

  zSql = sqlite3_mprintf("DELETE FROM " VEC0_SHADOW_CHUNKS_NAME
                         " WHERE chunk_id = ?",
                         p->schemaName, p->tableName);
  if (!zSql) {
    return SQLITE_NOMEM;
  }
  rc = sqlite3_prepare_v2(p->db, zSql, -1, &stmt, NULL);
  sqlite3_free(zSql);
  if (rc != SQLITE_OK) {
    return rc;
  }
  sqlite3_bind_int64(stmt, 1, chunk_id);
  rc = sqlite3_step(stmt);
  sqlite3_finalize(stmt);
  if (rc != SQLITE_DONE) {
    return vec0_error_rc(rc);
  }

  for (int i = 0; i < p->numVectorColumns; i++) {
    zSql = sqlite3_mprintf("DELETE FROM " VEC0_SHADOW_VECTOR_N_NAME
                           " WHERE rowid = ?",
                           p->schemaName, p->tableName, i);
    if (!zSql) {
      return SQLITE_NOMEM;
    }
    rc = sqlite3_prepare_v2(p->db, zSql, -1, &stmt, NULL);
    sqlite3_free(zSql);
    if (rc != SQLITE_OK) {
      return rc;
    }
    sqlite3_bind_int64(stmt, 1, chunk_id);
    rc = sqlite3_step(stmt);
    sqlite3_finalize(stmt);
    if (rc != SQLITE_DONE) {
      return vec0_error_rc(rc);
    }
  }

  for (int i = 0; i < p->numMetadataColumns; i++) {
    zSql = sqlite3_mprintf("DELETE FROM " VEC0_SHADOW_METADATA_N_NAME
                           " WHERE rowid = ?",
                           p->schemaName, p->tableName, i);
    if (!zSql) {
      return SQLITE_NOMEM;
    }
    rc = sqlite3_prepare_v2(p->db, zSql, -1, &stmt, NULL);
    sqlite3_free(zSql);
    if (rc != SQLITE_OK) {
      return rc;
    }
    sqlite3_bind_int64(stmt, 1, chunk_id);
    rc = sqlite3_step(stmt);
    sqlite3_finalize(stmt);
    if (rc != SQLITE_DONE) {
      return vec0_error_rc(rc);
    }
  }

  return SQLITE_OK;
}

int vec0Update_Delete(sqlite3_vtab *pVTab, sqlite3_value *idValue) {
  vec0_vtab *p = (vec0_vtab *)pVTab;
  int rc;
  i64 rowid;
  i64 chunk_id;
  i64 chunk_offset;

  if (p->pkIsText) {
    rc = vec0_rowid_from_id(p, idValue, &rowid);
    if (rc != SQLITE_OK) {
      return rc;
    }
  } else {
    rowid = sqlite3_value_int64(idValue);
  }

  // 1. Find chunk position for given rowid
  // 2. Ensure that validity bit for position is 1, then set to 0
  // 3. Zero out rowid in chunks.rowid
  // 4. Zero out vector data in all vector column chunks
  // 5. Delete value in _rowids table

  // 1. get chunk_id and chunk_offset from _rowids
  rc = vec0_get_chunk_position(p, rowid, NULL, &chunk_id, &chunk_offset);
  if (rc != SQLITE_OK) {
    return rc;
  }

  int chunkEmpty;
  rc = vec0Update_Delete_ClearValidity(p, chunk_id, chunk_offset, &chunkEmpty);
  if (rc != SQLITE_OK) {
    return rc;
  }

  // 3. zero out rowid in chunks.rowids
  // https://github.com/asg017/sqlite-vec/issues/54
  rc = vec0Update_Delete_ClearRowid(p, chunk_id, chunk_offset);
  if (rc != SQLITE_OK) {
    return rc;
  }

  // 4. zero out any data in vector chunks tables
  // https://github.com/asg017/sqlite-vec/issues/54
  rc = vec0Update_Delete_ClearVectors(p, chunk_id, chunk_offset);
  if (rc != SQLITE_OK) {
    return rc;
  }

  // 5. delete from _rowids table
  rc = vec0Update_Delete_DeleteRowids(p, rowid);
  if (rc != SQLITE_OK) {
    return rc;
  }

  // 6. delete any auxiliary rows
  if (p->numAuxiliaryColumns > 0) {
    rc = vec0Update_Delete_DeleteAux(p, rowid);
    if (rc != SQLITE_OK) {
      return rc;
    }
  }

  // 7. delete metadata
  for (int i = 0; i < p->numMetadataColumns; i++) {
    rc = vec0Update_Delete_ClearMetadata(p, i, rowid, chunk_id, chunk_offset);
    if (rc != SQLITE_OK) {
      return rc;
    }
  }

  // 8. delete the chunk if that was its last row
  if (chunkEmpty) {
    return vec0Update_Delete_DeleteChunk(p, chunk_id);
  }
  return SQLITE_OK;
}

int vec0Update_UpdateAuxColumn(vec0_vtab *p, int auxiliary_column_idx,
                               sqlite3_value *value, i64 rowid) {
  int rc;
  sqlite3_stmt *stmt;
  const char *zSql = sqlite3_mprintf(
      "UPDATE " VEC0_SHADOW_AUXILIARY_NAME " SET value%02d = ? WHERE rowid = ?",
      p->schemaName, p->tableName, auxiliary_column_idx);
  if (!zSql) {
    return SQLITE_NOMEM;
  }
  rc = sqlite3_prepare_v2(p->db, zSql, -1, &stmt, NULL);
  sqlite3_free((void *)zSql);
  if (rc != SQLITE_OK) {
    return rc;
  }
  sqlite3_bind_value(stmt, 1, value);
  sqlite3_bind_int64(stmt, 2, rowid);
  rc = sqlite3_step(stmt);
  if (rc != SQLITE_DONE) {
    sqlite3_finalize(stmt);
    return vec0_error_rc(rc);
  }
  sqlite3_finalize(stmt);
  return SQLITE_OK;
}

int vec0Update_UpdateVectorColumn(vec0_vtab *p, i64 chunk_id, i64 chunk_offset,
                                  int i, sqlite3_value *valueVector) {
  int rc;

  sqlite3_blob *blobVectors = NULL;

  char *pzError;
  size_t dimensions;
  enum VectorElementType elementType;
  void *vector = NULL;
  vector_cleanup cleanup = vector_cleanup_noop;
  // https://github.com/asg017/sqlite-vec/issues/53
  rc = vector_from_value(valueVector, &vector, &dimensions, &elementType,
                         &cleanup, &pzError);
  if (rc != SQLITE_OK) {
    // IMP: V15203_32042
    vtab_set_error(
        &p->base, "Updated vector for the \"%.*s\" column is invalid: %z",
        p->vector_columns[i].name_length, p->vector_columns[i].name, pzError);
    rc = SQLITE_ERROR;
    goto cleanup;
  }
  if (elementType != p->vector_columns[i].element_type) {
    // IMP: V03643_20481
    vtab_set_error(
        &p->base,
        "Updated vector for the \"%.*s\" column is expected to be of type "
        "%s, but a %s vector was provided.",
        p->vector_columns[i].name_length, p->vector_columns[i].name,
        vector_subtype_name(p->vector_columns[i].element_type),
        vector_subtype_name(elementType));
    rc = SQLITE_ERROR;
    goto cleanup;
  }
  if (dimensions != p->vector_columns[i].dimensions) {
    // IMP: V25739_09810
    vtab_set_error(
        &p->base,
        "Dimension mismatch for new updated vector for the \"%.*s\" column. "
        "Expected %d dimensions but received %d.",
        p->vector_columns[i].name_length, p->vector_columns[i].name,
        p->vector_columns[i].dimensions, dimensions);
    rc = SQLITE_ERROR;
    goto cleanup;
  }

  rc = sqlite3_blob_open(p->db, p->schemaName, p->shadowVectorChunksNames[i],
                         "vectors", chunk_id, 1, &blobVectors);
  if (rc != SQLITE_OK) {
    vtab_set_error(&p->base, "Could not open vectors blob for %s.%s.%lld",
                   p->schemaName, p->shadowVectorChunksNames[i], chunk_id);
    goto cleanup;
  }
  rc = vec0_write_vector_to_vector_blob(blobVectors, chunk_offset, vector,
                                        p->vector_columns[i].dimensions,
                                        p->vector_columns[i].element_type);
  if (rc != SQLITE_OK) {
    vtab_set_error(&p->base, "Could not write to vectors blob for %s.%s.%lld",
                   p->schemaName, p->shadowVectorChunksNames[i], chunk_id);
    goto cleanup;
  }

cleanup:
  cleanup(vector);
  int brc = sqlite3_blob_close(blobVectors);
  if (rc != SQLITE_OK) {
    return rc;
  }
  if (brc != SQLITE_OK) {
    vtab_set_error(
        &p->base,
        "Could not commit blob transaction for vectors blob for %s.%s.%lld",
        p->schemaName, p->shadowVectorChunksNames[i], chunk_id);
    return brc;
  }
  return SQLITE_OK;
}

int vec0Update_Update(sqlite3_vtab *pVTab, int argc, sqlite3_value **argv) {
  UNUSED_PARAMETER(argc);
  vec0_vtab *p = (vec0_vtab *)pVTab;
  int rc;
  i64 chunk_id;
  i64 chunk_offset;

  i64 rowid = 0;
  if (p->pkIsText) {
    // a stored text key never equals a value of another type; check the type
    // before sqlite3_value_text() converts the value
    int newIsText = sqlite3_value_type(argv[1]) == SQLITE_TEXT;
    const char *a = (const char *)sqlite3_value_text(argv[0]);
    const char *b = (const char *)sqlite3_value_text(argv[1]);
    // IMP: V08886_25725
    if (!newIsText ||
        (sqlite3_value_bytes(argv[0]) != sqlite3_value_bytes(argv[1])) ||
        memcmp(a, b, sqlite3_value_bytes(argv[0])) != 0) {
      vtab_set_error(pVTab,
                     "UPDATEs on vec0 primary key values are not allowed.");
      return SQLITE_ERROR;
    }
    rc = vec0_rowid_from_id(p, argv[0], &rowid);
    if (rc != SQLITE_OK) {
      return rc;
    }
  } else {
    rowid = sqlite3_value_int64(argv[0]);
    // On a table without a primary key column, `SET oid = ...` puts the new
    // key in argv[1] and `SET rowid = ...` in argv[2 + VEC0_COLUMN_ID]; on a
    // table with one, both hold the new key. As for an ordinary table's
    // INTEGER PRIMARY KEY, a value that converts to the same integer, such as
    // '1' or 1.0 for 1, leaves the key unchanged.
    sqlite3_value *newKeys[] = {argv[1], argv[2 + VEC0_COLUMN_ID]};
    for (int i = 0; i < 2; i++) {
      i64 newRowid;
      if (!vec0_value_as_rowid(newKeys[i], &newRowid) || newRowid != rowid) {
        vtab_set_error(pVTab,
                       "UPDATEs on vec0 primary key values are not allowed.");
        return SQLITE_ERROR;
      }
    }
  }

  // 1) get chunk_id and chunk_offset from _rowids
  rc = vec0_get_chunk_position(p, rowid, NULL, &chunk_id, &chunk_offset);
  if (rc != SQLITE_OK) {
    return rc;
  }

  // 2) update any partition key values
  for (int i = 0; i < vec0_num_defined_user_columns(p); i++) {
    if (p->user_column_kinds[i] != SQLITE_VEC0_USER_COLUMN_KIND_PARTITION) {
      continue;
    }
    sqlite3_value *value = argv[2 + VEC0_COLUMN_USERN_START + i];
    if (sqlite3_value_nochange(value)) {
      continue;
    }
    vtab_set_error(pVTab,
                   "UPDATE on partition key columns are not supported yet. ");
    return SQLITE_ERROR;
  }

  // 3) handle auxiliary column updates
  for (int i = 0; i < vec0_num_defined_user_columns(p); i++) {
    if (p->user_column_kinds[i] != SQLITE_VEC0_USER_COLUMN_KIND_AUXILIARY) {
      continue;
    }
    int auxiliary_column_idx = p->user_column_idxs[i];
    sqlite3_value *value = argv[2 + VEC0_COLUMN_USERN_START + i];
    if (sqlite3_value_nochange(value)) {
      continue;
    }
    rc = vec0Update_UpdateAuxColumn(p, auxiliary_column_idx, value, rowid);
    if (rc != SQLITE_OK) {
      return vec0_error_rc(rc);
    }
  }

  // 4) handle metadata column updates
  for (int i = 0; i < vec0_num_defined_user_columns(p); i++) {
    if (p->user_column_kinds[i] != SQLITE_VEC0_USER_COLUMN_KIND_METADATA) {
      continue;
    }
    int metadata_column_idx = p->user_column_idxs[i];
    sqlite3_value *value = argv[2 + VEC0_COLUMN_USERN_START + i];
    if (sqlite3_value_nochange(value)) {
      continue;
    }
    rc = vec0_write_metadata_value(p, metadata_column_idx, rowid, chunk_id,
                                   chunk_offset, value, 1);
    if (rc != SQLITE_OK) {
      return rc;
    }
  }

  // 5) iterate over all new vectors, update the vectors
  for (int i = 0; i < vec0_num_defined_user_columns(p); i++) {
    if (p->user_column_kinds[i] != SQLITE_VEC0_USER_COLUMN_KIND_VECTOR) {
      continue;
    }
    int vector_idx = p->user_column_idxs[i];
    sqlite3_value *valueVector = argv[2 + VEC0_COLUMN_USERN_START + i];
    // in vec0Column, we check sqlite3_vtab_nochange() on vector columns.
    // If the vector column isn't being changed, we return NULL;
    // That's not great, that means vector columns can never be NULLABLE
    // (bc we cant distinguish if an updated vector is truly NULL or nochange).
    // Also it means that if someone tries to run `UPDATE v SET X = NULL`,
    // we can't effectively detect and raise an error.
    // A better solution would be to use a custom result_type for "empty",
    // but subtypes don't appear to survive xColumn -> xUpdate, it's always 0.
    // So for now, we'll just use NULL and warn people to not SET X = NULL
    // in the docs.
    if (sqlite3_value_type(valueVector) == SQLITE_NULL) {
      continue;
    }

    rc = vec0Update_UpdateVectorColumn(p, chunk_id, chunk_offset, vector_idx,
                                       valueVector);
    if (rc != SQLITE_OK) {
      return vec0_error_rc(rc);
    }
  }

  return SQLITE_OK;
}

int vec0Update_SpecialInsert_OptimizeCopyMetadata(
    vec0_vtab *p, int metadata_column_idx, i64 src_chunk_id,
    i64 src_chunk_offset, i64 dst_chunk_id, i64 dst_chunk_offset) {
  int rc;
  struct Vec0MetadataColumnDefinition *metadata_column =
      &p->metadata_columns[metadata_column_idx];
  vec0_metadata_column_kind kind = metadata_column->kind;

  sqlite3_blob *srcBlob, *dstBlob;
  rc = sqlite3_blob_open(p->db, p->schemaName,
                         p->shadowMetadataChunksNames[metadata_column_idx],
                         "data", src_chunk_id, 0, &srcBlob);
  if (rc != SQLITE_OK) {
    vtab_set_error(&p->base, "Failed to open %s blob",
                   p->shadowMetadataChunksNames[metadata_column_idx]);
    return rc;
  }
  rc = sqlite3_blob_open(p->db, p->schemaName,
                         p->shadowMetadataChunksNames[metadata_column_idx],
                         "data", dst_chunk_id, 1, &dstBlob);
  if (rc != SQLITE_OK) {
    vtab_set_error(&p->base, "Failed to open %s blob",
                   p->shadowMetadataChunksNames[metadata_column_idx]);
    sqlite3_blob_close(srcBlob);
    return rc;
  }

  // Defensive: both metadata chunk blobs must be exactly the size this column's
  // kind implies, and both offsets must be valid slots in [0, chunk_size). On
  // any mismatch, return SQLITE_ERROR instead of issuing a blob read/write
  // against malformed state -- a recoverable error the caller can catch is
  // always preferable to corrupting memory or aborting the host process.
  i64 expectedSize = vec0_metadata_chunk_size(kind, p->chunk_size);
  if (sqlite3_blob_bytes(srcBlob) != expectedSize ||
      sqlite3_blob_bytes(dstBlob) != expectedSize) {
    vtab_set_error(&p->base,
                   "Internal error: metadata chunk blob size mismatch during "
                   "optimize on %s, expected %lld",
                   p->shadowMetadataChunksNames[metadata_column_idx],
                   (i64)expectedSize);
    rc = SQLITE_ERROR;
    goto done;
  }
  if (src_chunk_offset < 0 || src_chunk_offset >= p->chunk_size ||
      dst_chunk_offset < 0 || dst_chunk_offset >= p->chunk_size) {
    vtab_set_error(&p->base,
                   "Internal error: metadata chunk offset out of range during "
                   "optimize on %s",
                   p->shadowMetadataChunksNames[metadata_column_idx]);
    rc = SQLITE_ERROR;
    goto done;
  }

  switch (kind) {
  case VEC0_METADATA_COLUMN_KIND_BOOLEAN: {
    u8 srcBlock, dstBlock;
    rc = sqlite3_blob_read(srcBlob, &srcBlock, sizeof(u8),
                           (int)(src_chunk_offset / CHAR_BIT));
    if (rc != SQLITE_OK) {
      goto done;
    }
    int value = (srcBlock >> (src_chunk_offset % CHAR_BIT)) & 1;

    rc = sqlite3_blob_read(dstBlob, &dstBlock, sizeof(u8),
                           (int)(dst_chunk_offset / CHAR_BIT));
    if (rc != SQLITE_OK) {
      goto done;
    }
    if (value) {
      dstBlock |= 1 << (dst_chunk_offset % CHAR_BIT);
    } else {
      dstBlock &= ~(1 << (dst_chunk_offset % CHAR_BIT));
    }
    rc = sqlite3_blob_write(dstBlob, &dstBlock, sizeof(u8),
                            dst_chunk_offset / CHAR_BIT);
    if (rc != SQLITE_OK) {
      goto done;
    }
    break;
  }
  case VEC0_METADATA_COLUMN_KIND_INTEGER: {
    i64 value;
    rc = sqlite3_blob_read(srcBlob, &value, sizeof(i64),
                           src_chunk_offset * sizeof(i64));
    if (rc != SQLITE_OK) {
      goto done;
    }
    rc = sqlite3_blob_write(dstBlob, &value, sizeof(i64),
                            dst_chunk_offset * sizeof(i64));
    if (rc != SQLITE_OK) {
      goto done;
    }
    break;
  }
  case VEC0_METADATA_COLUMN_KIND_FLOAT: {
    double value;
    rc = sqlite3_blob_read(srcBlob, &value, sizeof(double),
                           src_chunk_offset * sizeof(double));
    if (rc != SQLITE_OK) {
      goto done;
    }
    rc = sqlite3_blob_write(dstBlob, &value, sizeof(double),
                            dst_chunk_offset * sizeof(double));
    if (rc != SQLITE_OK) {
      goto done;
    }
    break;
  }
  case VEC0_METADATA_COLUMN_KIND_TEXT: {
    u8 view[VEC0_METADATA_TEXT_VIEW_BUFFER_LENGTH];
    rc = sqlite3_blob_read(srcBlob, view, VEC0_METADATA_TEXT_VIEW_BUFFER_LENGTH,
                           src_chunk_offset *
                               VEC0_METADATA_TEXT_VIEW_BUFFER_LENGTH);
    if (rc != SQLITE_OK) {
      goto done;
    }
    rc = sqlite3_blob_write(
        dstBlob, view, VEC0_METADATA_TEXT_VIEW_BUFFER_LENGTH,
        dst_chunk_offset * VEC0_METADATA_TEXT_VIEW_BUFFER_LENGTH);
    if (rc != SQLITE_OK) {
      goto done;
    }
    break;
  }
  }
done: {
  // Always close both blobs, but do not let a successful close overwrite a
  // real read/write/validation error (the previous code masked the error with
  // the srcBlob close result, and leaked dstBlob when the srcBlob close
  // failed).
  int rcSrcClose = sqlite3_blob_close(srcBlob);
  int rcDstClose = sqlite3_blob_close(dstBlob);
  if (rc == SQLITE_OK) {
    rc = rcSrcClose;
  }
  if (rc == SQLITE_OK) {
    rc = rcDstClose;
  }
  return rc;
}
}

int vec0Update_SpecialInsert_Optimize(vec0_vtab *p) {
  sqlite3_stmt *stmt = NULL, *partition_key_stmt = NULL;
  int rc;
  const char *zSql;
  i64 prev_max_chunk_rowid = -1;
  sqlite3_value *partitionKeyValues[VEC0_MAX_PARTITION_COLUMNS];
  // Declared here (not inside the loop) and zero-initialized so the cleanup
  // label -- reached by gotos from before and inside the loop -- can safely
  // free whatever an error path still owns, without leaking or double-freeing.
  sqlite3_blob *blobChunksValidity = NULL;
  const unsigned char *bufferChunksValidity = NULL;
  void *vectorDatas[VEC0_MAX_VECTOR_COLUMNS] = {0};

  // 1) get the current maximum chunk_id
  zSql = sqlite3_mprintf("SELECT max(rowid) FROM " VEC0_SHADOW_CHUNKS_NAME,
                         p->schemaName, p->tableName);
  if (!zSql) {
    rc = SQLITE_NOMEM;
    goto done;
  }
  rc = sqlite3_prepare_v2(p->db, zSql, -1, &stmt, 0);
  sqlite3_free((void *)zSql);
  if ((rc != SQLITE_OK)) {
    rc = vec0_error_rc(rc);
    goto done;
  }
  rc = sqlite3_step(stmt);
  if (rc != SQLITE_ROW || sqlite3_column_type(stmt, 0) == SQLITE_NULL) {
    if (rc == SQLITE_ROW) {
      // no chunks to clear
      rc = SQLITE_OK;
    } else {
      rc = vec0_error_rc(rc);
    }
    goto cleanup;
  }
  prev_max_chunk_rowid = sqlite3_column_int64(stmt, 0);
  rc = sqlite3_step(stmt);
  if (rc != SQLITE_DONE) {
    rc = vec0_error_rc(rc);
    goto cleanup;
  }
  sqlite3_finalize(stmt);

  // 2) for each row get the chunk_id for its partition key (if any), if the
  // chunk_id is less than the previous maximum chunk_id, a new chunk needs to
  // be created
  zSql = sqlite3_mprintf(
      "SELECT rowid, chunk_id, chunk_offset FROM " VEC0_SHADOW_ROWIDS_NAME,
      p->schemaName, p->tableName);
  if (!zSql) {
    rc = SQLITE_NOMEM;
    goto done;
  }
  rc = sqlite3_prepare_v2(p->db, zSql, -1, &stmt, NULL);
  sqlite3_free((void *)zSql);
  if (rc != SQLITE_OK) {
    goto done;
  }

  if (p->numPartitionColumns > 0) {
    sqlite3_str *s = sqlite3_str_new(NULL);
    sqlite3_str_appendall(s, "SELECT ");
    for (int i = 0; i < p->numPartitionColumns; i++) {
      if (i == 0)
        sqlite3_str_appendf(s, "partition%02d", i);
      else
        sqlite3_str_appendf(s, ", partition%02d", i);
    }
    sqlite3_str_appendf(s, " FROM " VEC0_SHADOW_CHUNKS_NAME, p->schemaName,
                        p->tableName);
    sqlite3_str_appendall(s, " WHERE chunk_id = ?");
    zSql = sqlite3_str_finish(s);
    if (!zSql) {
      rc = SQLITE_NOMEM;
      goto cleanup;
    }
    rc = sqlite3_prepare_v2(p->db, zSql, -1, &partition_key_stmt, NULL);
    sqlite3_free((void *)zSql);
    if (rc != SQLITE_OK) {
      goto cleanup;
    }
  }

  i64 rowid, chunk_id, chunk_offset;
  i64 new_chunk_id, new_chunk_offset;
  while ((rc = sqlite3_step(stmt)) == SQLITE_ROW) {
    rowid = sqlite3_column_int64(stmt, 0);
    chunk_id = sqlite3_column_int64(stmt, 1);
    chunk_offset = sqlite3_column_int64(stmt, 2);

    // get the partition key for a row
    if (p->numPartitionColumns > 0) {
      sqlite3_reset(partition_key_stmt);
      sqlite3_clear_bindings(partition_key_stmt);
      sqlite3_bind_int64(partition_key_stmt, 1, chunk_id);
      rc = sqlite3_step(partition_key_stmt);
      if (rc != SQLITE_ROW) {
        rc = vec0_error_rc(rc);
        goto cleanup;
      }

      for (int i = 0; i < p->numPartitionColumns; i++) {
        partitionKeyValues[i] = sqlite3_column_value(partition_key_stmt, i);
      }
    }

    // get the latest chunk_id for a partition key
    rc = vec0_get_latest_chunk_rowid(p, &new_chunk_id, partitionKeyValues);
    if (rc != SQLITE_OK) {
      goto cleanup;
    }

    // create a new chunk if the latest chunk_id for a partition key is less
    // than the previous maximum chunk_id
    if (new_chunk_id <= prev_max_chunk_rowid) {
      rc = vec0_new_chunk(p, partitionKeyValues, NULL);
      if (rc != SQLITE_OK) {
        goto cleanup;
      }
    }
    // get the vector data from all vector columns of a row
    for (int i = 0; i < p->numVectorColumns; i++) {
      rc = vec0_get_vector_data(p, rowid, i, &vectorDatas[i], NULL);
      if (rc != SQLITE_OK) {
        goto cleanup;
      }
    }

    // find a valid slot in the new chunk
    rc = vec0Update_InsertNextAvailableStep(
        p, partitionKeyValues, &new_chunk_id, &new_chunk_offset,
        &blobChunksValidity, &bufferChunksValidity);
    if (rc != SQLITE_OK) {
      goto cleanup;
    }

    // write vector datas to the valid slot
    rc = vec0Update_InsertWriteFinalStep(p, new_chunk_id, new_chunk_offset,
                                         rowid, vectorDatas, blobChunksValidity,
                                         bufferChunksValidity);
    if (rc != SQLITE_OK) {
      goto cleanup;
    }
    sqlite3_free((void *)bufferChunksValidity);
    bufferChunksValidity = NULL;
    if (sqlite3_blob_close(blobChunksValidity) != SQLITE_OK) {
      // the handle is closed even on error; null it so cleanup won't re-close
      blobChunksValidity = NULL;
      rc = SQLITE_ERROR;
      vtab_set_error(&p->base, VEC_INTERAL_ERROR
                     "unknown error, blobChunksValidity could "
                     "not be closed, please file an issue");
      goto cleanup;
    }
    blobChunksValidity = NULL;

    // the per-row vector buffers were copied into the new chunk by
    // vec0Update_InsertWriteFinalStep and are no longer needed; free them so
    // they don't accumulate across a large optimize.
    for (int i = 0; i < p->numVectorColumns; i++) {
      sqlite3_free(vectorDatas[i]);
      vectorDatas[i] = NULL;
    }

    // copy metadata from previous chunk to new chunk
    for (int i = 0; i < p->numMetadataColumns; i++) {
      rc = vec0Update_SpecialInsert_OptimizeCopyMetadata(
          p, i, chunk_id, chunk_offset, new_chunk_id, new_chunk_offset);
      if (rc != SQLITE_OK) {
        goto cleanup;
      }
    }

    if (p->numPartitionColumns > 0) {
      rc = sqlite3_step(partition_key_stmt);
      if (rc != SQLITE_DONE) {
        rc = vec0_error_rc(rc);
        goto cleanup;
      }
    }
  }
  if (rc != SQLITE_DONE) {
    goto cleanup;
  }
  sqlite3_finalize(partition_key_stmt);
  sqlite3_finalize(stmt);
  partition_key_stmt = NULL;
  stmt = NULL;

  // 3) clean up old chunks
  zSql = sqlite3_mprintf("DELETE FROM " VEC0_SHADOW_CHUNKS_NAME
                         " WHERE chunk_id <= ?",
                         p->schemaName, p->tableName);
  rc = sqlite3_prepare_v2(p->db, zSql, -1, &stmt, 0);
  sqlite3_free((void *)zSql);
  if (rc != SQLITE_OK) {
    goto cleanup;
  }
  sqlite3_bind_int64(stmt, 1, prev_max_chunk_rowid);
  rc = sqlite3_step(stmt);
  if (rc != SQLITE_DONE) {
    rc = vec0_error_rc(rc);
    goto cleanup;
  }
  sqlite3_finalize(stmt);

  // 4) clean up old vector chunks
  for (int i = 0; i < p->numVectorColumns; i++) {
    zSql = sqlite3_mprintf("DELETE FROM " VEC0_SHADOW_VECTOR_N_NAME
                           " WHERE rowid <= ?",
                           p->schemaName, p->tableName, i);
    rc = sqlite3_prepare_v2(p->db, zSql, -1, &stmt, 0);
    sqlite3_free((void *)zSql);
    if (rc != SQLITE_OK) {
      goto cleanup;
    }
    sqlite3_bind_int64(stmt, 1, prev_max_chunk_rowid);
    rc = sqlite3_step(stmt);
    if (rc != SQLITE_DONE) {
      rc = vec0_error_rc(rc);
      goto cleanup;
    }
    sqlite3_finalize(stmt);
  }

  // 5) clean up old metadata chunks
  for (int i = 0; i < p->numMetadataColumns; i++) {
    zSql = sqlite3_mprintf("DELETE FROM " VEC0_SHADOW_METADATA_N_NAME
                           " WHERE rowid <= ?",
                           p->schemaName, p->tableName, i);
    rc = sqlite3_prepare_v2(p->db, zSql, -1, &stmt, 0);
    sqlite3_free((void *)zSql);
    if (rc != SQLITE_OK) {
      goto cleanup;
    }
    sqlite3_bind_int64(stmt, 1, prev_max_chunk_rowid);
    rc = sqlite3_step(stmt);
    if (rc != SQLITE_DONE) {
      rc = vec0_error_rc(rc);
      goto cleanup;
    }
    sqlite3_finalize(stmt);
  }

  stmt = NULL;
  rc = SQLITE_OK;

cleanup:
  sqlite3_finalize(partition_key_stmt);
  sqlite3_finalize(stmt);
  // Free anything an error path left owned. All of these are NULL on the normal
  // completion path (freed + nulled inside the loop), so this is a no-op then
  // and safe (sqlite3_free(NULL) / sqlite3_blob_close(NULL) are no-ops).
  sqlite3_free((void *)bufferChunksValidity);
  sqlite3_blob_close(blobChunksValidity);
  for (int i = 0; i < VEC0_MAX_VECTOR_COLUMNS; i++) {
    sqlite3_free(vectorDatas[i]);
  }
done:
  return rc;
}

int vec0Update_SpecialInsert(sqlite3_vtab *pVTab, sqlite3_value *pVal) {
  vec0_vtab *p = (vec0_vtab *)pVTab;

  const char *cmd = (const char *)sqlite3_value_text(pVal);
  int n_bytes = sqlite3_value_bytes(pVal);

  if (!cmd) {
    return SQLITE_NOMEM;
  }
  if (n_bytes == 8 && sqlite3_strnicmp(cmd, "optimize", 8) == 0) {
    return vec0Update_SpecialInsert_Optimize(p);
  }
  return SQLITE_ERROR;
}

static int vec0Update(sqlite3_vtab *pVTab, int argc, sqlite3_value **argv,
                      sqlite_int64 *pRowid) {
  // Special insert
  if (argc > 1 && sqlite3_value_type(argv[0]) == SQLITE_NULL &&
      ((vec0_vtab *)pVTab)->hasCommandColumn &&
      sqlite3_value_type(
          argv[2 + vec0_column_table_name_idx((vec0_vtab *)pVTab)]) !=
          SQLITE_NULL) {
    return vec0_interrupt_result(
        pVTab,
        vec0Update_SpecialInsert(
            pVTab, argv[2 + vec0_column_table_name_idx((vec0_vtab *)pVTab)]));
  }
  // DELETE operation
  if (argc == 1 && sqlite3_value_type(argv[0]) != SQLITE_NULL) {
    return vec0_interrupt_result(pVTab, vec0Update_Delete(pVTab, argv[0]));
  }
  // INSERT operation
  else if (argc > 1 && sqlite3_value_type(argv[0]) == SQLITE_NULL) {
    return vec0_interrupt_result(pVTab,
                                 vec0Update_Insert(pVTab, argc, argv, pRowid));
  }
  // UPDATE operation
  else if (argc > 1 && sqlite3_value_type(argv[0]) != SQLITE_NULL) {
    return vec0_interrupt_result(pVTab, vec0Update_Update(pVTab, argc, argv));
  } else {
    vtab_set_error(pVTab, "Unrecognized xUpdate operation provided for vec0.");
    return SQLITE_ERROR;
  }
}

static int vec0ShadowName(const char *zName) {
  static const char *azName[] = {
      "rowids",
      "chunks",
      "auxiliary",
      "info",

      // Up to VEC0_MAX_METADATA_COLUMNS
      // TODO be smarter about this man
      "metadatachunks00",
      "metadatachunks01",
      "metadatachunks02",
      "metadatachunks03",
      "metadatachunks04",
      "metadatachunks05",
      "metadatachunks06",
      "metadatachunks07",
      "metadatachunks08",
      "metadatachunks09",
      "metadatachunks10",
      "metadatachunks11",
      "metadatachunks12",
      "metadatachunks13",
      "metadatachunks14",
      "metadatachunks15",

      // Up to
      "metadatatext00",
      "metadatatext01",
      "metadatatext02",
      "metadatatext03",
      "metadatatext04",
      "metadatatext05",
      "metadatatext06",
      "metadatatext07",
      "metadatatext08",
      "metadatatext09",
      "metadatatext10",
      "metadatatext11",
      "metadatatext12",
      "metadatatext13",
      "metadatatext14",
      "metadatatext15",
  };

  for (size_t i = 0; i < sizeof(azName) / sizeof(azName[0]); i++) {
    if (sqlite3_stricmp(zName, azName[i]) == 0)
      return 1;
  }

  // "vector_chunksNN", one per vector column
  static const char zVectorChunks[] = "vector_chunks";
  size_t n = sizeof(zVectorChunks) - 1;
  if (sqlite3_strnicmp(zName, zVectorChunks, n) == 0 && zName[n] >= '0' &&
      zName[n] <= '9' && zName[n + 1] >= '0' && zName[n + 1] <= '9' &&
      zName[n + 2] == '\0') {
    return 1;
  }
  return 0;
}

static int vec0Begin(sqlite3_vtab *pVTab) {
  UNUSED_PARAMETER(pVTab);
  return SQLITE_OK;
}
static int vec0Sync(sqlite3_vtab *pVTab) {
  UNUSED_PARAMETER(pVTab);
  vec0_vtab *p = (vec0_vtab *)pVTab;
  if (p->stmtLatestChunk) {
    sqlite3_finalize(p->stmtLatestChunk);
    p->stmtLatestChunk = NULL;
  }
  if (p->stmtRowidsInsertRowid) {
    sqlite3_finalize(p->stmtRowidsInsertRowid);
    p->stmtRowidsInsertRowid = NULL;
  }
  if (p->stmtRowidsInsertId) {
    sqlite3_finalize(p->stmtRowidsInsertId);
    p->stmtRowidsInsertId = NULL;
  }
  if (p->stmtRowidsUpdatePosition) {
    sqlite3_finalize(p->stmtRowidsUpdatePosition);
    p->stmtRowidsUpdatePosition = NULL;
  }
  if (p->stmtRowidsGetChunkPosition) {
    sqlite3_finalize(p->stmtRowidsGetChunkPosition);
    p->stmtRowidsGetChunkPosition = NULL;
  }
  return SQLITE_OK;
}
static int vec0Commit(sqlite3_vtab *pVTab) {
  UNUSED_PARAMETER(pVTab);
  return SQLITE_OK;
}
static int vec0Rollback(sqlite3_vtab *pVTab) {
  UNUSED_PARAMETER(pVTab);
  return SQLITE_OK;
}

static int vec0Rename(sqlite3_vtab *pVTab, const char *zName) {
  vec0_vtab *p = (vec0_vtab *)pVTab;
  sqlite3_stmt *stmt;
  int rc;
  const char *zSql;

  vec0_free_resources(p);

  zSql = sqlite3_mprintf("ALTER TABLE " VEC0_SHADOW_CHUNKS_NAME
                         " RENAME TO \"%w_chunks\"",
                         p->schemaName, p->tableName, zName);
  rc = sqlite3_prepare_v2(p->db, zSql, -1, &stmt, 0);
  sqlite3_free((void *)zSql);
  if ((rc != SQLITE_OK) || (sqlite3_step(stmt) != SQLITE_DONE)) {
    rc = SQLITE_ERROR;
    vtab_set_error(pVTab, "could not rename chunks shadow table");
    goto done;
  }
  sqlite3_finalize(stmt);

  zSql = sqlite3_mprintf("ALTER TABLE " VEC0_SHADOW_INFO_NAME
                         " RENAME TO \"%w_info\"",
                         p->schemaName, p->tableName, zName);
  rc = sqlite3_prepare_v2(p->db, zSql, -1, &stmt, 0);
  sqlite3_free((void *)zSql);
  if ((rc != SQLITE_OK) || (sqlite3_step(stmt) != SQLITE_DONE)) {
    rc = SQLITE_ERROR;
    vtab_set_error(pVTab, "could not rename info shadow table");
    goto done;
  }
  sqlite3_finalize(stmt);

  zSql = sqlite3_mprintf("ALTER TABLE " VEC0_SHADOW_ROWIDS_NAME
                         " RENAME TO \"%w_rowids\"",
                         p->schemaName, p->tableName, zName);
  rc = sqlite3_prepare_v2(p->db, zSql, -1, &stmt, 0);
  sqlite3_free((void *)zSql);
  if ((rc != SQLITE_OK) || (sqlite3_step(stmt) != SQLITE_DONE)) {
    rc = SQLITE_ERROR;
    vtab_set_error(pVTab, "could not rename rowids shadow table");
    goto done;
  }
  sqlite3_finalize(stmt);

  for (int i = 0; i < p->numVectorColumns; i++) {
    char *newShadowVectorChunksName =
        sqlite3_mprintf("%s_vector_chunks%02d", zName, i);
    if (!newShadowVectorChunksName) {
      return SQLITE_NOMEM;
    }
    zSql = sqlite3_mprintf("ALTER TABLE \"%w\".\"%w\" RENAME TO \"%w\"",
                           p->schemaName, p->shadowVectorChunksNames[i],
                           newShadowVectorChunksName);
    sqlite3_free(newShadowVectorChunksName);
    rc = sqlite3_prepare_v2(p->db, zSql, -1, &stmt, 0);
    sqlite3_free((void *)zSql);
    if ((rc != SQLITE_OK) || (sqlite3_step(stmt) != SQLITE_DONE)) {
      rc = SQLITE_ERROR;
      vtab_set_error(pVTab, "could not rename vector_chunks shadow table");
      goto done;
    }
    sqlite3_finalize(stmt);
  }

  if (p->numAuxiliaryColumns > 0) {
    zSql = sqlite3_mprintf("ALTER TABLE " VEC0_SHADOW_AUXILIARY_NAME
                           " RENAME TO \"%w_auxiliary\"",
                           p->schemaName, p->tableName, zName);
    rc = sqlite3_prepare_v2(p->db, zSql, -1, &stmt, 0);
    sqlite3_free((void *)zSql);
    if ((rc != SQLITE_OK) || (sqlite3_step(stmt) != SQLITE_DONE)) {
      rc = SQLITE_ERROR;
      vtab_set_error(pVTab, "could not rename auxiliary shadow table");
      goto done;
    }
    sqlite3_finalize(stmt);
  }

  for (int i = 0; i < p->numMetadataColumns; i++) {
    zSql = sqlite3_mprintf("ALTER TABLE " VEC0_SHADOW_METADATA_N_NAME
                           " RENAME TO \"%w_metadatachunks%02d\"",
                           p->schemaName, p->tableName, i, zName, i);
    rc = sqlite3_prepare_v2(p->db, zSql, -1, &stmt, 0);
    sqlite3_free((void *)zSql);
    if ((rc != SQLITE_OK) || (sqlite3_step(stmt) != SQLITE_DONE)) {
      rc = SQLITE_ERROR;
      vtab_set_error(pVTab, "could not rename metadatachunks shadow table");
      goto done;
    }
    sqlite3_finalize(stmt);

    if (p->metadata_columns[i].kind == VEC0_METADATA_COLUMN_KIND_TEXT) {
      zSql = sqlite3_mprintf("ALTER TABLE " VEC0_SHADOW_METADATA_TEXT_DATA_NAME
                             " RENAME TO \"%w_metadatatext%02d\"",
                             p->schemaName, p->tableName, i, zName, i);
      rc = sqlite3_prepare_v2(p->db, zSql, -1, &stmt, 0);
      sqlite3_free((void *)zSql);
      if ((rc != SQLITE_OK) || (sqlite3_step(stmt) != SQLITE_DONE)) {
        rc = SQLITE_ERROR;
        vtab_set_error(pVTab, "could not rename metadatatext shadow table");
        goto done;
      }
      sqlite3_finalize(stmt);
    }
  }

  stmt = NULL;
  rc = SQLITE_OK;

done:
  sqlite3_finalize(stmt);
  return rc;
}

static sqlite3_module vec0Module = {
    /* iVersion      */ 3,
    /* xCreate       */ vec0Create,
    /* xConnect      */ vec0Connect,
    /* xBestIndex    */ vec0BestIndex,
    /* xDisconnect   */ vec0Disconnect,
    /* xDestroy      */ vec0Destroy,
    /* xOpen         */ vec0Open,
    /* xClose        */ vec0Close,
    /* xFilter       */ vec0Filter,
    /* xNext         */ vec0Next,
    /* xEof          */ vec0Eof,
    /* xColumn       */ vec0Column,
    /* xRowid        */ vec0Rowid,
    /* xUpdate       */ vec0Update,
    /* xBegin        */ vec0Begin,
    /* xSync         */ vec0Sync,
    /* xCommit       */ vec0Commit,
    /* xRollback     */ vec0Rollback,
    /* xFindFunction */ 0,
    /* xRename       */ vec0Rename,
    /* xSavepoint    */ 0,
    /* xRelease      */ 0,
    /* xRollbackTo   */ 0,
    /* xShadowName   */ vec0ShadowName,
#if SQLITE_VERSION_NUMBER >= 3044000
    /* xIntegrity    */ 0, // https://github.com/asg017/sqlite-vec/issues/44
#endif
};
#pragma endregion

static char *POINTER_NAME_STATIC_BLOB_DEF = "vec0-static_blob_def";
struct static_blob_definition {
  void *p;
  size_t dimensions;
  size_t nvectors;
  enum VectorElementType element_type;
};
static void vec_static_blob_from_raw(sqlite3_context *context, int argc,
                                     sqlite3_value **argv) {

  assert(argc == 4);
  struct static_blob_definition *p;
  p = sqlite3_malloc(sizeof(*p));
  if (!p) {
    sqlite3_result_error_nomem(context);
    return;
  }
  memset(p, 0, sizeof(*p));
  p->p = (void *)sqlite3_value_int64(argv[0]);
  p->element_type = SQLITE_VEC_ELEMENT_TYPE_FLOAT32;
  p->dimensions = sqlite3_value_int64(argv[2]);
  p->nvectors = sqlite3_value_int64(argv[3]);
  sqlite3_result_pointer(context, p, POINTER_NAME_STATIC_BLOB_DEF,
                         sqlite3_free);
}
#pragma region vec_static_blobs() table function

#define MAX_STATIC_BLOBS 16

typedef struct static_blob static_blob;
struct static_blob {
  char *name;
  void *p;
  size_t dimensions;
  size_t nvectors;
  enum VectorElementType element_type;
};

typedef struct vec_static_blob_data vec_static_blob_data;
struct vec_static_blob_data {
  static_blob static_blobs[MAX_STATIC_BLOBS];
};

/** Frees the registry and the names vec_static_blobsUpdate() copied in. */
static void vec_static_blob_data_free(void *p) {
  vec_static_blob_data *data = p;
  for (int i = 0; i < MAX_STATIC_BLOBS; i++) {
    sqlite3_free(data->static_blobs[i].name);
  }
  sqlite3_free(data);
}

typedef struct vec_static_blobs_vtab vec_static_blobs_vtab;
struct vec_static_blobs_vtab {
  sqlite3_vtab base;
  vec_static_blob_data *data;
};

typedef struct vec_static_blobs_cursor vec_static_blobs_cursor;
struct vec_static_blobs_cursor {
  sqlite3_vtab_cursor base;
  sqlite3_int64 iRowid;
};

static int vec_static_blobsConnect(sqlite3 *db, void *pAux, int argc,
                                   const char *const *argv,
                                   sqlite3_vtab **ppVtab, char **pzErr) {
  UNUSED_PARAMETER(argc);
  UNUSED_PARAMETER(argv);
  UNUSED_PARAMETER(pzErr);

  vec_static_blobs_vtab *pNew;
#define VEC_STATIC_BLOBS_NAME 0
#define VEC_STATIC_BLOBS_DATA 1
#define VEC_STATIC_BLOBS_DIMENSIONS 2
#define VEC_STATIC_BLOBS_COUNT 3
  int rc = sqlite3_declare_vtab(
      db, "CREATE TABLE x(name, data, dimensions hidden, count hidden)");
  if (rc == SQLITE_OK) {
    pNew = sqlite3_malloc(sizeof(*pNew));
    *ppVtab = (sqlite3_vtab *)pNew;
    if (pNew == 0)
      return SQLITE_NOMEM;
    memset(pNew, 0, sizeof(*pNew));
    pNew->data = pAux;
  }
  return rc;
}

static int vec_static_blobsDisconnect(sqlite3_vtab *pVtab) {
  vec_static_blobs_vtab *p = (vec_static_blobs_vtab *)pVtab;
  sqlite3_free(p);
  return SQLITE_OK;
}

static int vec_static_blobsUpdate(sqlite3_vtab *pVTab, int argc,
                                  sqlite3_value **argv, sqlite_int64 *pRowid) {
  UNUSED_PARAMETER(pRowid);
  vec_static_blobs_vtab *p = (vec_static_blobs_vtab *)pVTab;
  // DELETE operation
  if (argc == 1 && sqlite3_value_type(argv[0]) != SQLITE_NULL) {
    return SQLITE_ERROR;
  }
  // INSERT operation
  else if (argc > 1 && sqlite3_value_type(argv[0]) == SQLITE_NULL) {
    const char *key =
        (const char *)sqlite3_value_text(argv[2 + VEC_STATIC_BLOBS_NAME]);
    int idx = -1;
    for (int i = 0; i < MAX_STATIC_BLOBS; i++) {
      if (!p->data->static_blobs[i].name) {
        p->data->static_blobs[i].name = sqlite3_mprintf("%s", key);
        idx = i;
        break;
      }
    }
    if (idx < 0)
      abort();
    struct static_blob_definition *def = sqlite3_value_pointer(
        argv[2 + VEC_STATIC_BLOBS_DATA], POINTER_NAME_STATIC_BLOB_DEF);
    p->data->static_blobs[idx].p = def->p;
    p->data->static_blobs[idx].dimensions = def->dimensions;
    p->data->static_blobs[idx].nvectors = def->nvectors;
    p->data->static_blobs[idx].element_type = def->element_type;

    return SQLITE_OK;
  }
  // UPDATE operation
  else if (argc > 1 && sqlite3_value_type(argv[0]) != SQLITE_NULL) {
    return SQLITE_ERROR;
  }
  return SQLITE_ERROR;
}

static int vec_static_blobsOpen(sqlite3_vtab *p,
                                sqlite3_vtab_cursor **ppCursor) {
  UNUSED_PARAMETER(p);
  vec_static_blobs_cursor *pCur;
  pCur = sqlite3_malloc(sizeof(*pCur));
  if (pCur == 0)
    return SQLITE_NOMEM;
  memset(pCur, 0, sizeof(*pCur));
  *ppCursor = &pCur->base;
  return SQLITE_OK;
}

static int vec_static_blobsClose(sqlite3_vtab_cursor *cur) {
  vec_static_blobs_cursor *pCur = (vec_static_blobs_cursor *)cur;
  sqlite3_free(pCur);
  return SQLITE_OK;
}

static int vec_static_blobsBestIndex(sqlite3_vtab *pVTab,
                                     sqlite3_index_info *pIdxInfo) {
  UNUSED_PARAMETER(pVTab);
  pIdxInfo->idxNum = 1;
  pIdxInfo->estimatedCost = (double)10;
  pIdxInfo->estimatedRows = 10;
  return SQLITE_OK;
}

static int vec_static_blobsNext(sqlite3_vtab_cursor *cur);
static int vec_static_blobsFilter(sqlite3_vtab_cursor *pVtabCursor, int idxNum,
                                  const char *idxStr, int argc,
                                  sqlite3_value **argv) {
  UNUSED_PARAMETER(idxNum);
  UNUSED_PARAMETER(idxStr);
  UNUSED_PARAMETER(argc);
  UNUSED_PARAMETER(argv);
  vec_static_blobs_cursor *pCur = (vec_static_blobs_cursor *)pVtabCursor;
  pCur->iRowid = -1;
  vec_static_blobsNext(pVtabCursor);
  return SQLITE_OK;
}

static int vec_static_blobsRowid(sqlite3_vtab_cursor *cur,
                                 sqlite_int64 *pRowid) {
  vec_static_blobs_cursor *pCur = (vec_static_blobs_cursor *)cur;
  *pRowid = pCur->iRowid;
  return SQLITE_OK;
}

static int vec_static_blobsNext(sqlite3_vtab_cursor *cur) {
  vec_static_blobs_cursor *pCur = (vec_static_blobs_cursor *)cur;
  vec_static_blobs_vtab *p = (vec_static_blobs_vtab *)pCur->base.pVtab;
  pCur->iRowid++;
  while (pCur->iRowid < MAX_STATIC_BLOBS) {
    if (p->data->static_blobs[pCur->iRowid].name) {
      return SQLITE_OK;
    }
    pCur->iRowid++;
  }
  return SQLITE_OK;
}

static int vec_static_blobsEof(sqlite3_vtab_cursor *cur) {
  vec_static_blobs_cursor *pCur = (vec_static_blobs_cursor *)cur;
  return pCur->iRowid >= MAX_STATIC_BLOBS;
}

static int vec_static_blobsColumn(sqlite3_vtab_cursor *cur,
                                  sqlite3_context *context, int i) {
  vec_static_blobs_cursor *pCur = (vec_static_blobs_cursor *)cur;
  vec_static_blobs_vtab *p = (vec_static_blobs_vtab *)cur->pVtab;
  switch (i) {
  case VEC_STATIC_BLOBS_NAME:
    sqlite3_result_text(context, p->data->static_blobs[pCur->iRowid].name, -1,
                        SQLITE_TRANSIENT);
    break;
  case VEC_STATIC_BLOBS_DATA:
    sqlite3_result_null(context);
    break;
  case VEC_STATIC_BLOBS_DIMENSIONS:
    sqlite3_result_int64(context,
                         p->data->static_blobs[pCur->iRowid].dimensions);
    break;
  case VEC_STATIC_BLOBS_COUNT:
    sqlite3_result_int64(context, p->data->static_blobs[pCur->iRowid].nvectors);
    break;
  }
  return SQLITE_OK;
}

static sqlite3_module vec_static_blobsModule = {
    /* iVersion    */ 3,
    /* xCreate     */ 0,
    /* xConnect    */ vec_static_blobsConnect,
    /* xBestIndex  */ vec_static_blobsBestIndex,
    /* xDisconnect */ vec_static_blobsDisconnect,
    /* xDestroy    */ 0,
    /* xOpen       */ vec_static_blobsOpen,
    /* xClose      */ vec_static_blobsClose,
    /* xFilter     */ vec_static_blobsFilter,
    /* xNext       */ vec_static_blobsNext,
    /* xEof        */ vec_static_blobsEof,
    /* xColumn     */ vec_static_blobsColumn,
    /* xRowid      */ vec_static_blobsRowid,
    /* xUpdate     */ vec_static_blobsUpdate,
    /* xBegin      */ 0,
    /* xSync       */ 0,
    /* xCommit     */ 0,
    /* xRollback   */ 0,
    /* xFindMethod */ 0,
    /* xRename     */ 0,
    /* xSavepoint  */ 0,
    /* xRelease    */ 0,
    /* xRollbackTo */ 0,
    /* xShadowName */ 0,
#if SQLITE_VERSION_NUMBER >= 3044000
    /* xIntegrity  */ 0
#endif
};
#pragma endregion

#pragma region vec_static_blob_entries() table function

typedef struct vec_static_blob_entries_vtab vec_static_blob_entries_vtab;
struct vec_static_blob_entries_vtab {
  sqlite3_vtab base;
  static_blob *blob;
};
typedef enum {
  VEC_SBE__QUERYPLAN_FULLSCAN = 1,
  VEC_SBE__QUERYPLAN_KNN = 2
} vec_sbe_query_plan;

struct sbe_query_knn_data {
  i64 k;
  i64 k_used;
  // Array of rowids of size k. Must be freed with sqlite3_free().
  i32 *rowids;
  // Array of distances of size k. Must be freed with sqlite3_free().
  f32 *distances;
  i64 current_idx;
};
void sbe_query_knn_data_clear(struct sbe_query_knn_data *knn_data) {
  if (!knn_data)
    return;

  if (knn_data->rowids) {
    sqlite3_free(knn_data->rowids);
    knn_data->rowids = NULL;
  }
  if (knn_data->distances) {
    sqlite3_free(knn_data->distances);
    knn_data->distances = NULL;
  }
}

typedef struct vec_static_blob_entries_cursor vec_static_blob_entries_cursor;
struct vec_static_blob_entries_cursor {
  sqlite3_vtab_cursor base;
  sqlite3_int64 iRowid;
  vec_sbe_query_plan query_plan;
  struct sbe_query_knn_data *knn_data;
};

static int vec_static_blob_entriesConnect(sqlite3 *db, void *pAux, int argc,
                                          const char *const *argv,
                                          sqlite3_vtab **ppVtab, char **pzErr) {
  UNUSED_PARAMETER(argc);
  UNUSED_PARAMETER(argv);
  UNUSED_PARAMETER(pzErr);
  vec_static_blob_data *blob_data = pAux;
  int idx = -1;
  for (int i = 0; i < MAX_STATIC_BLOBS; i++) {
    if (!blob_data->static_blobs[i].name)
      continue;
    if (strncmp(blob_data->static_blobs[i].name, argv[3],
                strlen(blob_data->static_blobs[i].name)) == 0) {
      idx = i;
      break;
    }
  }
  if (idx < 0)
    abort();
  vec_static_blob_entries_vtab *pNew;
#define VEC_STATIC_BLOB_ENTRIES_VECTOR 0
#define VEC_STATIC_BLOB_ENTRIES_DISTANCE 1
#define VEC_STATIC_BLOB_ENTRIES_K 2
  int rc = sqlite3_declare_vtab(
      db, "CREATE TABLE x(vector, distance hidden, k hidden)");
  if (rc == SQLITE_OK) {
    pNew = sqlite3_malloc(sizeof(*pNew));
    *ppVtab = (sqlite3_vtab *)pNew;
    if (pNew == 0)
      return SQLITE_NOMEM;
    memset(pNew, 0, sizeof(*pNew));
    pNew->blob = &blob_data->static_blobs[idx];
  }
  return rc;
}

static int vec_static_blob_entriesCreate(sqlite3 *db, void *pAux, int argc,
                                         const char *const *argv,
                                         sqlite3_vtab **ppVtab, char **pzErr) {
  return vec_static_blob_entriesConnect(db, pAux, argc, argv, ppVtab, pzErr);
}

static int vec_static_blob_entriesDisconnect(sqlite3_vtab *pVtab) {
  vec_static_blob_entries_vtab *p = (vec_static_blob_entries_vtab *)pVtab;
  sqlite3_free(p);
  return SQLITE_OK;
}

static int vec_static_blob_entriesOpen(sqlite3_vtab *p,
                                       sqlite3_vtab_cursor **ppCursor) {
  UNUSED_PARAMETER(p);
  vec_static_blob_entries_cursor *pCur;
  pCur = sqlite3_malloc(sizeof(*pCur));
  if (pCur == 0)
    return SQLITE_NOMEM;
  memset(pCur, 0, sizeof(*pCur));
  *ppCursor = &pCur->base;
  return SQLITE_OK;
}

static int vec_static_blob_entriesClose(sqlite3_vtab_cursor *cur) {
  vec_static_blob_entries_cursor *pCur = (vec_static_blob_entries_cursor *)cur;
  if (pCur->knn_data) {
    sbe_query_knn_data_clear(pCur->knn_data);
    sqlite3_free(pCur->knn_data);
  }
  sqlite3_free(pCur);
  return SQLITE_OK;
}

static int vec_static_blob_entriesBestIndex(sqlite3_vtab *pVTab,
                                            sqlite3_index_info *pIdxInfo) {
  vec_static_blob_entries_vtab *p = (vec_static_blob_entries_vtab *)pVTab;
  int iMatchTerm = -1;
  int iLimitTerm = -1;
  // int iRowidTerm = -1; // https://github.com/asg017/sqlite-vec/issues/47
  int iKTerm = -1;

  for (int i = 0; i < pIdxInfo->nConstraint; i++) {
    if (!pIdxInfo->aConstraint[i].usable)
      continue;

    int iColumn = pIdxInfo->aConstraint[i].iColumn;
    int op = pIdxInfo->aConstraint[i].op;
    if (op == SQLITE_INDEX_CONSTRAINT_MATCH &&
        iColumn == VEC_STATIC_BLOB_ENTRIES_VECTOR) {
      if (iMatchTerm > -1) {
        // https://github.com/asg017/sqlite-vec/issues/51
        return SQLITE_ERROR;
      }
      iMatchTerm = i;
    }
    if (op == SQLITE_INDEX_CONSTRAINT_LIMIT) {
      iLimitTerm = i;
    }
    if (op == SQLITE_INDEX_CONSTRAINT_EQ &&
        iColumn == VEC_STATIC_BLOB_ENTRIES_K) {
      iKTerm = i;
    }
  }
  if (iMatchTerm >= 0) {
    if (iLimitTerm < 0 && iKTerm < 0) {
      // https://github.com/asg017/sqlite-vec/issues/51
      return SQLITE_ERROR;
    }
    if (iLimitTerm >= 0 && iKTerm >= 0) {
      return SQLITE_ERROR; // limit or k, not both
    }
    if (pIdxInfo->nOrderBy < 1) {
      vtab_set_error(pVTab, "ORDER BY distance required");
      return SQLITE_CONSTRAINT;
    }
    if (pIdxInfo->nOrderBy > 1) {
      // https://github.com/asg017/sqlite-vec/issues/51
      vtab_set_error(pVTab, "more than 1 ORDER BY clause provided");
      return SQLITE_CONSTRAINT;
    }
    if (pIdxInfo->aOrderBy[0].iColumn != VEC_STATIC_BLOB_ENTRIES_DISTANCE) {
      vtab_set_error(pVTab, "ORDER BY must be on the distance column");
      return SQLITE_CONSTRAINT;
    }
    if (pIdxInfo->aOrderBy[0].desc) {
      vtab_set_error(pVTab,
                     "Only ascending in ORDER BY distance clause is supported, "
                     "DESC is not supported yet.");
      return SQLITE_CONSTRAINT;
    }

    pIdxInfo->idxNum = VEC_SBE__QUERYPLAN_KNN;
    pIdxInfo->estimatedCost = (double)10;
    pIdxInfo->estimatedRows = 10;

    pIdxInfo->orderByConsumed = 1;
    pIdxInfo->aConstraintUsage[iMatchTerm].argvIndex = 1;
    pIdxInfo->aConstraintUsage[iMatchTerm].omit = 1;
    if (iLimitTerm >= 0) {
      pIdxInfo->aConstraintUsage[iLimitTerm].argvIndex = 2;
      pIdxInfo->aConstraintUsage[iLimitTerm].omit = 1;
    } else {
      pIdxInfo->aConstraintUsage[iKTerm].argvIndex = 2;
      pIdxInfo->aConstraintUsage[iKTerm].omit = 1;
    }

  } else {
    pIdxInfo->idxNum = VEC_SBE__QUERYPLAN_FULLSCAN;
    pIdxInfo->estimatedCost = (double)p->blob->nvectors;
    pIdxInfo->estimatedRows = p->blob->nvectors;
  }
  return SQLITE_OK;
}

static int vec_static_blob_entriesFilter(sqlite3_vtab_cursor *pVtabCursor,
                                         int idxNum, const char *idxStr,
                                         int argc, sqlite3_value **argv) {
  UNUSED_PARAMETER(idxStr);
  assert(argc >= 0 && argc <= 3);
  vec_static_blob_entries_cursor *pCur =
      (vec_static_blob_entries_cursor *)pVtabCursor;
  vec_static_blob_entries_vtab *p =
      (vec_static_blob_entries_vtab *)pCur->base.pVtab;

  if (idxNum == VEC_SBE__QUERYPLAN_KNN) {
    assert(argc == 2);
    pCur->query_plan = VEC_SBE__QUERYPLAN_KNN;
    int rc = SQLITE_OK;
    struct sbe_query_knn_data *knn_data = NULL;
    void *queryVector = NULL;
    vector_cleanup queryVectorCleanup = vector_cleanup_noop;
    i32 *topk_rowids = NULL;
    f32 *distances = NULL;
    u8 *candidates = NULL;

    knn_data = sqlite3_malloc(sizeof(*knn_data));
    if (!knn_data) {
      rc = SQLITE_NOMEM;
      goto knn_cleanup;
    }
    memset(knn_data, 0, sizeof(*knn_data));

    size_t dimensions;
    enum VectorElementType elementType;
    char *err;
    rc = vector_from_value(argv[0], &queryVector, &dimensions, &elementType,
                           &queryVectorCleanup, &err);
    if (rc != SQLITE_OK) {
      rc = SQLITE_ERROR;
      goto knn_cleanup;
    }
    if (elementType != p->blob->element_type) {
      rc = SQLITE_ERROR;
      goto knn_cleanup;
    }
    if (dimensions != p->blob->dimensions) {
      rc = SQLITE_ERROR;
      goto knn_cleanup;
    }

    i64 k = min(sqlite3_value_int64(argv[1]), (i64)p->blob->nvectors);
    if (k < 0) {
      rc = SQLITE_ERROR;
      goto knn_cleanup;
    }
    if (k == 0) {
      knn_data->k = 0;
      pCur->knn_data = knn_data;
      queryVectorCleanup(queryVector);
      return SQLITE_OK;
    }

    size_t bsize = (p->blob->nvectors + 7) & ~7;

    topk_rowids = sqlite3_malloc(k * sizeof(i32));
    if (!topk_rowids) {
      rc = SQLITE_NOMEM;
      goto knn_cleanup;
    }
    distances = sqlite3_malloc(bsize * sizeof(f32));
    if (!distances) {
      rc = SQLITE_NOMEM;
      goto knn_cleanup;
    }

    for (size_t i = 0; i < p->blob->nvectors; i++) {
      float *v = ((float *)p->blob->p) + (i * p->blob->dimensions);
      distances[i] =
          distance_l2_sqr_float(v, (float *)queryVector, &p->blob->dimensions);
    }

    candidates = bitmap_new(bsize);
    if (!candidates) {
      rc = SQLITE_NOMEM;
      goto knn_cleanup;
    }

    bitmap_fill(candidates, bsize);
    for (size_t i = p->blob->nvectors; i < bsize; i++) {
      bitmap_set(candidates, i, 0);
    }
    i32 k_used = 0;
    min_idx(distances, bsize, candidates, topk_rowids, k, &k_used);
    knn_data->current_idx = 0;
    knn_data->distances = distances;
    knn_data->k = k;
    knn_data->rowids = topk_rowids;

    pCur->knn_data = knn_data;

    // Cleanup temporaries (not owned by knn_data)
    queryVectorCleanup(queryVector);
    sqlite3_free(candidates);
    return SQLITE_OK;

  knn_cleanup:
    queryVectorCleanup(queryVector);
    sqlite3_free(knn_data);
    sqlite3_free(topk_rowids);
    sqlite3_free(distances);
    sqlite3_free(candidates);
    return rc;
  } else {
    pCur->query_plan = VEC_SBE__QUERYPLAN_FULLSCAN;
    pCur->iRowid = 0;
  }

  return SQLITE_OK;
}

static int vec_static_blob_entriesRowid(sqlite3_vtab_cursor *cur,
                                        sqlite_int64 *pRowid) {
  vec_static_blob_entries_cursor *pCur = (vec_static_blob_entries_cursor *)cur;
  switch (pCur->query_plan) {
  case VEC_SBE__QUERYPLAN_FULLSCAN: {
    *pRowid = pCur->iRowid;
    return SQLITE_OK;
  }
  case VEC_SBE__QUERYPLAN_KNN: {
    i32 rowid = ((i32 *)pCur->knn_data->rowids)[pCur->knn_data->current_idx];
    *pRowid = (sqlite3_int64)rowid;
    return SQLITE_OK;
  }
  }
  return SQLITE_ERROR;
}

static int vec_static_blob_entriesNext(sqlite3_vtab_cursor *cur) {
  vec_static_blob_entries_cursor *pCur = (vec_static_blob_entries_cursor *)cur;
  switch (pCur->query_plan) {
  case VEC_SBE__QUERYPLAN_FULLSCAN: {
    pCur->iRowid++;
    return SQLITE_OK;
  }
  case VEC_SBE__QUERYPLAN_KNN: {
    pCur->knn_data->current_idx++;
    return SQLITE_OK;
  }
  }
  return SQLITE_ERROR;
}

static int vec_static_blob_entriesEof(sqlite3_vtab_cursor *cur) {
  vec_static_blob_entries_cursor *pCur = (vec_static_blob_entries_cursor *)cur;
  vec_static_blob_entries_vtab *p =
      (vec_static_blob_entries_vtab *)pCur->base.pVtab;
  switch (pCur->query_plan) {
  case VEC_SBE__QUERYPLAN_FULLSCAN: {
    return (size_t)pCur->iRowid >= p->blob->nvectors;
  }
  case VEC_SBE__QUERYPLAN_KNN: {
    return pCur->knn_data->current_idx >= pCur->knn_data->k;
  }
  }
  return SQLITE_ERROR;
}

static int vec_static_blob_entriesColumn(sqlite3_vtab_cursor *cur,
                                         sqlite3_context *context, int i) {
  vec_static_blob_entries_cursor *pCur = (vec_static_blob_entries_cursor *)cur;
  vec_static_blob_entries_vtab *p = (vec_static_blob_entries_vtab *)cur->pVtab;

  switch (pCur->query_plan) {
  case VEC_SBE__QUERYPLAN_FULLSCAN: {
    switch (i) {
    case VEC_STATIC_BLOB_ENTRIES_VECTOR:

      sqlite3_result_blob(
          context,
          ((unsigned char *)p->blob->p) +
              (pCur->iRowid * p->blob->dimensions * sizeof(float)),
          p->blob->dimensions * sizeof(float), SQLITE_TRANSIENT);
      sqlite3_result_subtype(context, p->blob->element_type);
      break;
    }
    return SQLITE_OK;
  }
  case VEC_SBE__QUERYPLAN_KNN: {
    switch (i) {
    case VEC_STATIC_BLOB_ENTRIES_VECTOR: {
      i32 rowid = ((i32 *)pCur->knn_data->rowids)[pCur->knn_data->current_idx];
      sqlite3_result_blob(context,
                          ((unsigned char *)p->blob->p) +
                              (rowid * p->blob->dimensions * sizeof(float)),
                          p->blob->dimensions * sizeof(float),
                          SQLITE_TRANSIENT);
      sqlite3_result_subtype(context, p->blob->element_type);
      break;
    }
    }
    return SQLITE_OK;
  }
  }
  return SQLITE_ERROR;
}

static sqlite3_module vec_static_blob_entriesModule = {
    /* iVersion    */ 3,
    /* xCreate     */
    vec_static_blob_entriesCreate, // handle rm?
                                   // https://github.com/asg017/sqlite-vec/issues/55
    /* xConnect    */ vec_static_blob_entriesConnect,
    /* xBestIndex  */ vec_static_blob_entriesBestIndex,
    /* xDisconnect */ vec_static_blob_entriesDisconnect,
    /* xDestroy    */ vec_static_blob_entriesDisconnect,
    /* xOpen       */ vec_static_blob_entriesOpen,
    /* xClose      */ vec_static_blob_entriesClose,
    /* xFilter     */ vec_static_blob_entriesFilter,
    /* xNext       */ vec_static_blob_entriesNext,
    /* xEof        */ vec_static_blob_entriesEof,
    /* xColumn     */ vec_static_blob_entriesColumn,
    /* xRowid      */ vec_static_blob_entriesRowid,
    /* xUpdate     */ 0,
    /* xBegin      */ 0,
    /* xSync       */ 0,
    /* xCommit     */ 0,
    /* xRollback   */ 0,
    /* xFindMethod */ 0,
    /* xRename     */ 0,
    /* xSavepoint  */ 0,
    /* xRelease    */ 0,
    /* xRollbackTo */ 0,
    /* xShadowName */ 0,
#if SQLITE_VERSION_NUMBER >= 3044000
    /* xIntegrity  */ 0
#endif
};
#pragma endregion

#ifdef SQLITE_VEC_ENABLE_AVX
#define SQLITE_VEC_DEBUG_BUILD_AVX "avx"
#else
#define SQLITE_VEC_DEBUG_BUILD_AVX ""
#endif
#ifdef SQLITE_VEC_ENABLE_NEON
#define SQLITE_VEC_DEBUG_BUILD_NEON "neon"
#else
#define SQLITE_VEC_DEBUG_BUILD_NEON ""
#endif

#define SQLITE_VEC_DEBUG_BUILD                                                 \
  SQLITE_VEC_DEBUG_BUILD_AVX " " SQLITE_VEC_DEBUG_BUILD_NEON

#define SQLITE_VEC_DEBUG_STRING                                                \
  "Version: " SQLITE_VEC_VERSION "\n"                                          \
  "Date: " SQLITE_VEC_DATE "\n"                                                \
  "Commit: " SQLITE_VEC_SOURCE "\n"                                            \
  "Build flags: " SQLITE_VEC_DEBUG_BUILD

SQLITE_VEC_API int sqlite3_vec_init(sqlite3 *db, char **pzErrMsg,
                                    const sqlite3_api_routines *pApi) {
#ifndef SQLITE_CORE
  SQLITE_EXTENSION_INIT2(pApi);
#else
  UNUSED_PARAMETER(pApi);
#endif
  int rc = SQLITE_OK;

#define DEFAULT_FLAGS (SQLITE_UTF8 | SQLITE_INNOCUOUS | SQLITE_DETERMINISTIC)

  rc = sqlite3_create_function_v2(db, "vec_version", 0, DEFAULT_FLAGS,
                                  SQLITE_VEC_VERSION, _static_text_func, NULL,
                                  NULL, NULL);
  if (rc != SQLITE_OK) {
    return rc;
  }
  rc = sqlite3_create_function_v2(db, "vec_debug", 0, DEFAULT_FLAGS,
                                  SQLITE_VEC_DEBUG_STRING, _static_text_func,
                                  NULL, NULL, NULL);
  if (rc != SQLITE_OK) {
    return rc;
  }
  static struct {
    const char *zFName;
    void (*xFunc)(sqlite3_context *, int, sqlite3_value **);
    int nArg;
    int flags;
  } aFunc[] = {
      // clang-format off
    //{"vec_version",         _static_text_func,    0, DEFAULT_FLAGS,                                          (void *) SQLITE_VEC_VERSION },
    //{"vec_debug",           _static_text_func,    0, DEFAULT_FLAGS,                                          (void *) SQLITE_VEC_DEBUG_STRING },
    {"vec_distance_l2",     vec_distance_l2,      2, DEFAULT_FLAGS | SQLITE_SUBTYPE,                         },
    {"vec_distance_l1",     vec_distance_l1,      2, DEFAULT_FLAGS | SQLITE_SUBTYPE,                         },
    {"vec_distance_hamming",vec_distance_hamming, 2, DEFAULT_FLAGS | SQLITE_SUBTYPE,                         },
    {"vec_distance_cosine", vec_distance_cosine,  2, DEFAULT_FLAGS | SQLITE_SUBTYPE,                         },
    {"vec_length",          vec_length,           1, DEFAULT_FLAGS | SQLITE_SUBTYPE,                         },
    {"vec_type",           vec_type,           1, DEFAULT_FLAGS,                         },
    {"vec_to_json",         vec_to_json,          1, DEFAULT_FLAGS | SQLITE_SUBTYPE | SQLITE_RESULT_SUBTYPE, },
    {"vec_add",             vec_add,              2, DEFAULT_FLAGS | SQLITE_SUBTYPE | SQLITE_RESULT_SUBTYPE, },
    {"vec_sub",             vec_sub,              2, DEFAULT_FLAGS | SQLITE_SUBTYPE | SQLITE_RESULT_SUBTYPE, },
    {"vec_slice",           vec_slice,            3, DEFAULT_FLAGS | SQLITE_SUBTYPE | SQLITE_RESULT_SUBTYPE, },
    {"vec_normalize",       vec_normalize,        1, DEFAULT_FLAGS | SQLITE_SUBTYPE | SQLITE_RESULT_SUBTYPE, },
    {"vec_f32",             vec_f32,              1, DEFAULT_FLAGS | SQLITE_SUBTYPE | SQLITE_RESULT_SUBTYPE, },
    {"vec_bit",             vec_bit,              1, DEFAULT_FLAGS | SQLITE_SUBTYPE | SQLITE_RESULT_SUBTYPE, },
    {"vec_int8",            vec_int8,             1, DEFAULT_FLAGS | SQLITE_SUBTYPE | SQLITE_RESULT_SUBTYPE, },
    {"vec_quantize_int8",     vec_quantize_int8,      2, DEFAULT_FLAGS | SQLITE_SUBTYPE | SQLITE_RESULT_SUBTYPE, },
    {"vec_quantize_binary", vec_quantize_binary,  1, DEFAULT_FLAGS | SQLITE_SUBTYPE | SQLITE_RESULT_SUBTYPE, },
      // clang-format on
  };

  static struct {
    char *name;
    const sqlite3_module *module;
    void *p;
    void (*xDestroy)(void *);
  } aMod[] = {
      // clang-format off
    {"vec0",          &vec0Module,          NULL, NULL},
    {"vec_each",      &vec_eachModule,      NULL, NULL},
      // clang-format on
  };

  for (unsigned long i = 0; i < countof(aFunc) && rc == SQLITE_OK; i++) {
    rc = sqlite3_create_function_v2(db, aFunc[i].zFName, aFunc[i].nArg,
                                    aFunc[i].flags, NULL, aFunc[i].xFunc, NULL,
                                    NULL, NULL);
    if (rc != SQLITE_OK) {
      *pzErrMsg = sqlite3_mprintf("Error creating function %s: %s",
                                  aFunc[i].zFName, sqlite3_errmsg(db));
      return rc;
    }
  }

  for (unsigned long i = 0; i < countof(aMod) && rc == SQLITE_OK; i++) {
    rc = sqlite3_create_module_v2(db, aMod[i].name, aMod[i].module, NULL, NULL);
    if (rc != SQLITE_OK) {
      *pzErrMsg = sqlite3_mprintf("Error creating module %s: %s", aMod[i].name,
                                  sqlite3_errmsg(db));
      return rc;
    }
  }

  return SQLITE_OK;
}

#ifndef SQLITE_VEC_OMIT_FS
SQLITE_VEC_API int sqlite3_vec_numpy_init(sqlite3 *db, char **pzErrMsg,
                                          const sqlite3_api_routines *pApi) {
  UNUSED_PARAMETER(pzErrMsg);
#ifndef SQLITE_CORE
  SQLITE_EXTENSION_INIT2(pApi);
#else
  UNUSED_PARAMETER(pApi);
#endif
  int rc = SQLITE_OK;
  rc = sqlite3_create_function_v2(db, "vec_npy_file", 1, SQLITE_RESULT_SUBTYPE,
                                  NULL, vec_npy_file, NULL, NULL, NULL);
  if (rc != SQLITE_OK) {
    return rc;
  }
  rc = sqlite3_create_module_v2(db, "vec_npy_each", &vec_npy_eachModule, NULL,
                                NULL);
  return rc;
}
#endif

SQLITE_VEC_API int
sqlite3_vec_static_blobs_init(sqlite3 *db, char **pzErrMsg,
                              const sqlite3_api_routines *pApi) {
  UNUSED_PARAMETER(pzErrMsg);
#ifndef SQLITE_CORE
  SQLITE_EXTENSION_INIT2(pApi);
#else
  UNUSED_PARAMETER(pApi);
#endif

  int rc = SQLITE_OK;
  vec_static_blob_data *static_blob_data;
  static_blob_data = sqlite3_malloc(sizeof(*static_blob_data));
  if (!static_blob_data) {
    return SQLITE_NOMEM;
  }
  memset(static_blob_data, 0, sizeof(*static_blob_data));

  rc = sqlite3_create_function_v2(
      db, "vec_static_blob_from_raw", 4,
      DEFAULT_FLAGS | SQLITE_SUBTYPE | SQLITE_RESULT_SUBTYPE, NULL,
      vec_static_blob_from_raw, NULL, NULL, NULL);
  if (rc != SQLITE_OK)
    return rc;

  rc = sqlite3_create_module_v2(db, "vec_static_blobs", &vec_static_blobsModule,
                                static_blob_data, vec_static_blob_data_free);
  if (rc != SQLITE_OK)
    return rc;
  rc = sqlite3_create_module_v2(db, "vec_static_blob_entries",
                                &vec_static_blob_entriesModule,
                                static_blob_data, NULL);
  if (rc != SQLITE_OK)
    return rc;
  return rc;
}