semoss-vector

name

semoss-vector

description

Use when writing code in an app that does semantic search, RAG, or ingests documents into a vector database on the platform — running nearest-neighbor queries, listing/adding/removing documents, or feeding retrieved chunks into an LLM. Covers VectorDatabaseQuery(), ListDocumentsInVectorDatabase(), CreateEmbeddingsFromDocuments(), CreateEmbeddingsFromVectorCSVFile(), and RemoveDocumentFromVectorDatabase() pixel commands via the Semoss SDK, plus listing engines with MyEngines(engineTypes=["VECTOR"]). Do not use for raw SQL/graph queries (see semoss-database) or direct LLM calls without retrieval (see semoss-model).

Vector Engine

Query and manage a vector database on the platform using actions.run() from the useInsight() hook with the VectorDatabaseQuery() pixel command as the primary entry point. Results are typically passed into an LLM() call to implement RAG — see the RAG pattern section below.

Usage

import { useInsight } from "@semoss/sdk/react";

const { actions } = useInsight();
const VECTOR_ID = "1222b449-1bc6-4358-9398-1ed828e4f26a";
const query = "Time sheet";

const { pixelReturn } = await actions.run(
  `VectorDatabaseQuery(engine=${JSON.stringify(VECTOR_ID)}, command=${JSON.stringify(query)}, limit=5, filters=[], metaFilters=[]);`,
);

if (pixelReturn[0].operationType.includes("ERROR")) {
  throw new Error(pixelReturn[0].output as string);
}

const hits = pixelReturn[0].output as Array<{
  Score: number;
  idx: number;
  Source: string;
  Modality: string;
  Divider: string;
  Part: string;
  Tokens: number;
  Content: string;
  Weighted_RRF_Score: number;
  BM25_Score: number;
}>;

Each hit carries both the text chunk (Content) and the source document (Source), plus hybrid-search scoring fields. Lower Score is closer; Weighted_RRF_Score and BM25_Score are the underlying component scores from the hybrid rank fusion.

The variations below show only the pixel string — the one that goes inside the actions.run() template literal. The surrounding actions.run(...) call, the error check, and the response parsing are the same as above.

Filtering by source document

filters is an array of Filter() expressions matched against the chunk's Source. Use this to restrict retrieval to a named subset of documents.

VectorDatabaseQuery(engine="${VECTOR_ID}", command="${query}", limit=5, filters=[Filter(Source == ["doc1.pdf", "doc2.pdf"])]);

Filtering by metadata

metaFilters is an array of Filter() expressions matched against arbitrary metadata keys attached to chunks at embed time.

VectorDatabaseQuery(engine="${VECTOR_ID}", command="${query}", limit=5, metaFilters=[Filter(department == "finance")]);

Both filters and metaFilters can be combined in the same call.

Listing documents in the vector index

Returns one entry per unique Source currently indexed.

ListDocumentsInVectorDatabase(engine="${VECTOR_ID}");

Response shape (at pixelReturn[0].output):

Array<{ fileName: string; fileSize: number; lastModified: string }>;

Adding documents from the current insight

Use when the files were uploaded into the current insight/room workspace. CreateEmbeddingsFromDocuments handles the chunking, embedding, and indexing.

CreateEmbeddingsFromDocuments(engine="${VECTOR_ID}", filePaths=["fileName1.pdf", "fileName2.pdf"]);

Adding documents from app or user space

When the files live outside the current insight — in a project/app folder or the user's personal space — pass space. Use space="app_id" where app_id is the project/app UUID, or space="user" for the user space.

CreateEmbeddingsFromDocuments(engine="${VECTOR_ID}", filePaths=["docs/file1.pdf"], space="app_id");

Adding pre-chunked CSV data

Use CreateEmbeddingsFromVectorCSVFile when you have already chunked the source material and want to skip the platform's default splitter. Supported inputs: .csv files, or .zip archives containing CSV files.

The CSV must have exactly these headers, case-sensitive:

Source,Modality,Divider,Part,Tokens,Content
doc1.pdf,text,1,0,120,"First chunk of text"

Quotes on values are optional unless a value contains commas, newlines, or quotes.

CreateEmbeddingsFromVectorCSVFile(engine="${VECTOR_ID}", filePaths=["fileName1.csv", "fileName2.csv"]);

Use the same space argument as CreateEmbeddingsFromDocuments when the CSVs live in app or user space:

CreateEmbeddingsFromVectorCSVFile(engine="${VECTOR_ID}", filePaths=["vector_data/chunks.csv"], space="app_id");

Removing documents from the vector index

Pass fileNames — the source identifiers as listed by ListDocumentsInVectorDatabase, not file paths.

RemoveDocumentFromVectorDatabase(engine="${VECTOR_ID}", fileNames=["fileName1.pdf", "fileName2.pdf"]);

Response shape

Unlike SqlQuery (which returns a tabular { data: { values, headers } } object), vector pixels return their payload directly at pixelReturn[0].output:

• VectorDatabaseQuery → array of hit objects with Score, Source, Content, etc.
• ListDocumentsInVectorDatabase → array of { fileName, fileSize, lastModified }.
• CreateEmbeddingsFromDocuments / CreateEmbeddingsFromVectorCSVFile → string status ("Successfully embedded all files") plus a structured additionalOutput[] with per-file { fileName, status, insertedRecords, failedRecords, totalRecords }.
• RemoveDocumentFromVectorDatabase → status payload confirming the removal.

For the full response schema of each pixel, see references/response-schema.md.

RAG pattern

The typical flow is a two-step chain: retrieve chunks with VectorDatabaseQuery, then feed them into an LLM() call as grounding context. See the model skill for the LLM half.

import { useInsight } from "@semoss/sdk/react";

const { actions } = useInsight();
const VECTOR_ID = "1222b449-1bc6-4358-9398-1ed828e4f26a";
const MODEL_ID = "6dd0bbfd-cd3b-4f2c-b13a-fe4545872e3d";
const question = "Time sheet";

const { pixelReturn: retrievalReturn } = await actions.run(
  `VectorDatabaseQuery(engine=${JSON.stringify(VECTOR_ID)}, command=${JSON.stringify(question)}, limit=3);`,
);

const hits = retrievalReturn[0].output as Array<{ Source: string; Content: string }>;
const context = hits
  .map((h) => `* Document Name: ${h.Source}, ${h.Content}`)
  .join("\n");

const prompt = `Answer the question using only the context below.\n\nQuestion: ${question}\n\nContext:\n\`\`\`\n${context}\n\`\`\``;

const { pixelReturn: answerReturn } = await actions.run(
  `LLM(engine=${JSON.stringify(MODEL_ID)}, command=[${JSON.stringify(prompt)}], paramValues=[{"temperature":0.1}]);`,
);

const answer = answerReturn[0].output.response;

Keep the prompt explicit about citing Source and Part/Divider so the model's reasoning trace references the retrieved chunks.

Listing available vector engines

Before querying, you often need to let the user pick a vector database — or find one programmatically. Use MyEngines with engineTypes=["VECTOR"].

import { useInsight } from "@semoss/sdk/react";

const { actions } = useInsight();

const { pixelReturn } = await actions.run(
  `MyEngines(engineTypes=["VECTOR"], limit=[50], offset=[0]);`
);

if (pixelReturn[0].operationType.includes("ERROR")) {
  throw new Error(pixelReturn[0].output as string);
}

const vectorEngines = pixelReturn[0].output as Array<{
  engine_id: string;
  engine_name: string;
  engine_display_name: string;
  engine_subtype: string;   // e.g. "FAISS", "CHROMA", "WEAVIATE"
  engine_cost: string;
  engine_favorite: 0 | 1;
}>;

Filtering and paging

MyEngines accepts several optional arguments. All are arrays, even when passing a single value:

• filterWord=["policy"] — substring match against engine name.
• limit=[50], offset=[0] — paging. Omit both to return all results.
• onlyFavorites=[true] — restrict to the user's favorited engines.
• sort={"ENGINENAME": "ASC"} — sort by ENGINENAME or DATECREATED, direction ASC or DESC.

MyEngines(engineTypes=["VECTOR"], filterWord=["policy"], sort={"ENGINENAME": "ASC"}, limit=[20], offset=[0]);

Response field conventions

Use engine_* fields (engine_id, engine_name, engine_display_name, engine_subtype, etc.). The response also contains app_* and database_* fields with the same values — these are legacy aliases and should not be used in new code.

Common pattern — render a picker and use the selected engine_id as VECTOR_ID in the VectorDatabaseQuery() call above:

const [engines, setEngines] = useState<VectorEngine[]>([]);
const [selectedId, setSelectedId] = useState<string>("");

useEffect(() => {
  actions.run(`MyEngines(engineTypes=["VECTOR"], limit=[50], offset=[0]);`)
    .then(({ pixelReturn }) => setEngines(pixelReturn[0].output));
}, [actions]);

Vector engine response schemas

Full response shapes returned from runPixel calls that wrap the vector pixels: VectorDatabaseQuery, ListDocumentsInVectorDatabase, CreateEmbeddingsFromDocuments, CreateEmbeddingsFromVectorCSVFile, and RemoveDocumentFromVectorDatabase. Each call has a common envelope and a pixel-specific output.

Note: unlike SqlQuery, whose output wraps rows in { data: { values, headers } }, vector pixels put the payload directly at pixelReturn[0].output — usually a raw array or string.

Envelope fields

Same envelope as every other pixel call:

• insightID — insight ID used for the pixel execution.
• pixelReturn[] — array of results, one per pixel command in the call. For a single vector pixel, always index [0].

Each pixelReturn[i] carries pixelId, pixelExpression (the parsed pixel SEMOSS actually executed — useful for debugging encoding), isMeta, timeToRun (ms), and operationType. For successful embedding calls, operationType is ["SUCCESS"]; for queries and listings it is ["OPERATION"].

VectorDatabaseQuery output

pixelReturn[0].output is an array of hit objects ranked by hybrid similarity.

Example response

{
    "insightID": "019dbb4c-db55-7ea8-bc46-41c95ec49287",
    "pixelReturn": [
        {
            "pixelId": "3",
          "pixelExpression": "VectorDatabaseQuery ( engine = \"1222b449-1bc6-4358-9398-1ed828e4f26a\" , command = 'Time sheet' , limit = 3 ) ;",
            "isMeta": false,
            "timeToRun": 1027,
            "output": [
                {
                    "Score": 0.6172683238983154,
                    "idx": 2,
                    "Source": "timesheet_guide.pdf",
                    "Modality": "text",
                    "Divider": "1",
                    "Part": "2",
                    "Tokens": 132,
                    "Content": "advise that you will use the manual timesheet form until the WBS code is made available...",
                    "Weighted_RRF_Score": 0.004918032786885246,
                    "BM25_Score": 0.05683182179927826
                }
            ],
            "operationType": ["OPERATION"]
        }
    ]
}

Hit fields

• Score (number) — combined hybrid-search score. Lower is closer.
• idx (number) — internal chunk index within the vector store.
• Source (string) — source document identifier (e.g. "timesheet_guide.pdf"). Pass this back in filters to scope future queries.
• Modality (string) — chunk modality: "text", etc.
• Divider (string) — page / section boundary the chunk came from. Often maps 1:1 to page number for PDFs.
• Part (string) — chunk ordinal within the Divider ("0", "1", ...).
• Tokens (number) — token count of the chunk's Content.
• Content (string) — the chunk text to feed into an LLM prompt.
• Weighted_RRF_Score (number) — reciprocal-rank-fusion component of the hybrid score.
• BM25_Score (number) — lexical BM25 component of the hybrid score.

ListDocumentsInVectorDatabase output

pixelReturn[0].output is an array with one entry per unique Source currently indexed.

{
    "insightID": "019dbb4c-db55-7ea8-bc46-41c95ec49287",
    "pixelReturn": [
        {
            "pixelId": "7",
            "pixelExpression": "ListDocumentsInVectorDatabase ( engine = \"1222b449-1bc6-4358-9398-1ed828e4f26a\" ) ;",
            "isMeta": false,
            "timeToRun": 19,
            "output": [
                {
                    "fileName": "timesheet_guide.pdf",
                    "fileSize": 198.26953125,
                    "lastModified": "2026-03-27 12:22:27"
                }
            ],
            "operationType": ["OPERATION"]
        }
    ]
}

• fileName (string) — source identifier. Use this as the Source in filters and as fileNames when removing.
• fileSize (number) — size in kilobytes.
• lastModified (string) — ISO-like timestamp ("YYYY-MM-DD HH:mm:ss").

CreateEmbeddingsFromDocuments / CreateEmbeddingsFromVectorCSVFile output

pixelReturn[0].output is a status string. Per-file detail lives in pixelReturn[0].additionalOutput[0].output.

{
    "insightID": "019dbb4c-db55-7ea8-bc46-41c95ec49287",
    "pixelReturn": [
        {
            "pixelId": "8",
            "pixelExpression": "CreateEmbeddingsFromDocuments ( engine = \"1222b449-1bc6-4358-9398-1ed828e4f26a\" , filePaths = [ \"/130_WEILER1103_OF306.pdf\" ] ) ;",
            "isMeta": false,
            "timeToRun": 3338,
            "output": "Successfully embedded all files",
            "operationType": ["SUCCESS"],
            "additionalOutput": [
                {
                    "output": [
                        {
                            "fileName": "130_WEILER1103_OF306.csv",
                            "status": "SUCCESS",
                            "insertedRecords": 1,
                            "failedRecords": 0,
                            "totalRecords": 1
                        }
                    ],
                    "operationType": ["OPERATION"]
                }
            ]
        }
    ]
}

• output (string) — human-readable summary ("Successfully embedded all files" on full success).
• operationType — ["SUCCESS"] for the top-level operation status.
• additionalOutput[0].output[] — per-file record: { fileName, status, insertedRecords, failedRecords, totalRecords }. For mixed-result batches, inspect this array to find partial failures. fileName here is the normalized CSV name the platform produced, not necessarily the original upload name.

RemoveDocumentFromVectorDatabase output

Same envelope shape as the embedding calls — a status string at output plus a per-file breakdown in additionalOutput. Check operationType for "SUCCESS" and inspect additionalOutput if you need per-file confirmation.

Common access patterns

// Retrieve and use content chunks
const hits = pixelReturn[0].output as Array<{ Source: string; Content: string; Score: number }>;
const contextBlock = hits
  .map((h) => `* Document Name: ${h.Source}\n${h.Content}`)
  .join("\n\n");

// Group hits by source document
const bySource = hits.reduce<Record<string, typeof hits>>((acc, h) => {
  (acc[h.Source] ??= []).push(h);
  return acc;
}, {});

// Check embedding success
const success = pixelReturn[0].operationType.includes("SUCCESS");
const perFile = pixelReturn[0].additionalOutput?.[0]?.output ?? [];
const failed = perFile.filter((f) => f.status !== "SUCCESS");