From 09fff9881ec1de2016463528dab3f65941b72e50 Mon Sep 17 00:00:00 2001
From: Benjamin Toby <devops@tben.me>
Date: Wed, 11 Feb 2026 05:14:25 +0100
Subject: [PATCH] Updates

---
 dist/package-shared/types/index.d.ts | 33 ++++++++++++++++++++++++++++
 package-shared/types/index.ts        | 33 ++++++++++++++++++++++++++++
 package.json                         |  2 +-
 3 files changed, 67 insertions(+), 1 deletion(-)

diff --git a/dist/package-shared/types/index.d.ts b/dist/package-shared/types/index.d.ts
index 2c23c18..ece4097 100644
--- a/dist/package-shared/types/index.d.ts
+++ b/dist/package-shared/types/index.d.ts
@@ -131,6 +131,39 @@ export type DSQL_FieldSchemaType = {
     options?: string[];
     isVector?: boolean;
     vectorSize?: number;
+    /**
+     * ### Adds a `+` prefix to colums
+     *  In sqlite-vec, the + prefix is a specialized syntax for Virtual Table Columns. It essentially tells the database: "Keep this data associated with the vector, but don't try to index it for math."
+Here is the breakdown of why they matter and how they work:
+1. Performance Separation
+In a standard table, adding a massive TEXT column (like a 2,000-word article) slows down full-table scans. In a vec0 virtual table, columns prefixed with + are stored in a separate internal side-car table.
+The Vector Index: Stays lean and fast for "Nearest Neighbor" math.
+The Content: Is only fetched after the vector search identifies the winning rows.
+2. The "No Join" Convenience
+Normally, you would store vectors in one table and the actual text content in another, linking them with a FOREIGN KEY.
+Without + columns: You must JOIN two tables to get the text after finding the vector.
+With + columns: You can SELECT content directly from the virtual table. It handles the "join" logic internally, making your code cleaner.
+3. Syntax Example
+When defining your schema, the + is only used in the CREATE statement. When querying or inserting, you treat it like a normal name.
+```sql
+-- SCHEMA DEFINITION
+CREATE VIRTUAL TABLE documents USING vec0(
+  embedding float,     -- The vector (indexed)
+  +title TEXT,         -- Side-car metadata (not indexed)
+  +raw_body TEXT       -- Side-car "heavy" data (not indexed)
+);
+
+-- INSERTING (Notice: No '+' here)
+INSERT INTO documents(embedding, title, raw_body)
+VALUES (vec_f32(?), 'Bun Docs', 'Bun is a fast JavaScript runtime...');
+
+-- QUERYING (Notice: No '+' here)
+SELECT title, raw_body
+FROM documents
+WHERE embedding MATCH ? AND k = 1;
+```
+     */
+    sideCar?: boolean;
 } & {
     [key in (typeof TextFieldTypesArray)[number]["value"]]?: boolean;
 };
diff --git a/package-shared/types/index.ts b/package-shared/types/index.ts
index 7afc699..d8cf1ee 100644
--- a/package-shared/types/index.ts
+++ b/package-shared/types/index.ts
@@ -162,6 +162,39 @@ export type DSQL_FieldSchemaType = {
     options?: string[];
     isVector?: boolean;
     vectorSize?: number;
+    /**
+     * ### Adds a `+` prefix to colums
+     *  In sqlite-vec, the + prefix is a specialized syntax for Virtual Table Columns. It essentially tells the database: "Keep this data associated with the vector, but don't try to index it for math."
+Here is the breakdown of why they matter and how they work:
+1. Performance Separation
+In a standard table, adding a massive TEXT column (like a 2,000-word article) slows down full-table scans. In a vec0 virtual table, columns prefixed with + are stored in a separate internal side-car table.
+The Vector Index: Stays lean and fast for "Nearest Neighbor" math.
+The Content: Is only fetched after the vector search identifies the winning rows.
+2. The "No Join" Convenience
+Normally, you would store vectors in one table and the actual text content in another, linking them with a FOREIGN KEY.
+Without + columns: You must JOIN two tables to get the text after finding the vector.
+With + columns: You can SELECT content directly from the virtual table. It handles the "join" logic internally, making your code cleaner.
+3. Syntax Example
+When defining your schema, the + is only used in the CREATE statement. When querying or inserting, you treat it like a normal name.
+```sql
+-- SCHEMA DEFINITION
+CREATE VIRTUAL TABLE documents USING vec0(
+  embedding float,     -- The vector (indexed)
+  +title TEXT,         -- Side-car metadata (not indexed)
+  +raw_body TEXT       -- Side-car "heavy" data (not indexed)
+);
+
+-- INSERTING (Notice: No '+' here)
+INSERT INTO documents(embedding, title, raw_body) 
+VALUES (vec_f32(?), 'Bun Docs', 'Bun is a fast JavaScript runtime...');
+
+-- QUERYING (Notice: No '+' here)
+SELECT title, raw_body 
+FROM documents 
+WHERE embedding MATCH ? AND k = 1;
+```
+     */
+    sideCar?: boolean;
 } & {
     [key in (typeof TextFieldTypesArray)[number]["value"]]?: boolean;
 };
diff --git a/package.json b/package.json
index d38f6b2..932ad88 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
     "name": "@moduletrace/datasquirel",
-    "version": "5.7.37",
+    "version": "5.7.38",
     "description": "Cloud-based SQL data management tool",
     "main": "dist/index.js",
     "bin": {