ExuluReadApi

ExuluReadApi provides low-level, RBAC-enforced read functions for knowledge contexts. Where ExuluContext.search() covers relevance-ranked retrieval, ExuluReadApi covers targeted reads by item ID or external ID, embed-query utilities, and table-name resolution — all while applying the same access-control rules as the GraphQL layer. Use ExuluReadApi when you need to read specific known items without going through vector search, or when you need the underlying table names to build custom queries.

API surface

ExuluReadApi.authorizedRead

ExuluReadApi.authorizedRead(
  context: { id: string; fields?: unknown[]; entities?: unknown },
  user: User,
  role: string,
  opts?: {
    itemIds?: string[];
    externalIds?: string[];
    chunkIndexRange?: { from?: number; to?: number };
  },
): Promise<VectorSearchChunkResult[]>

Reads chunks from a context, joining them to their parent items and applying RBAC via applyAccessControl. At least itemIds or externalIds must be supplied — unconstrained full-table reads are rejected.

object

required

The context to read from. Must have an id matching a registered ExuluContext.

User

required

Authenticated user. Used for RBAC filtering on the items table.

string

required

Role ID. Merged into the user object so access-control’s role branch works correctly.

string[]

Filter to chunks whose parent item ID is in this list.

string[]

Filter to chunks whose parent item external_id is in this list.

{ from?: number; to?: number }

Restrict to a contiguous range of chunk_index values within the matched items.

Promise<VectorSearchChunkResult[]>

Chunk rows with joined item metadata, ordered by (source, chunk_index).

ExuluReadApi.embedQuery

ExuluReadApi.embedQuery(
  context: { id: string; name?: string; embedder: { model: string } },
  text: string,
  opts?: {
    user?: User;
    role?: string;
    inputType?: "document" | "query";
  },
): Promise<number[]>

Embeds a text string using the context’s configured embedder model. Returns the embedding vector as a number array.

object

required

Context descriptor. id must match a registered ExuluContext; embedder.model selects the LiteLLM embedding model.

string

required

The text to embed.

User

Authenticated user. Forwarded to resolveEmbedder for spend attribution.

string

Role ID forwarded to resolveEmbedder for access-control tagging.

"document" | "query"

Hint passed to the embedding model. Controls Matryoshka / asymmetric embedding direction where the model supports it. Defaults to "query".

Promise<number[]>

The embedding vector. Returns an empty array when the embedder produces no output.

ExuluReadApi.entitiesAvailable

ExuluReadApi.entitiesAvailable(
  context: { id: string; entities?: unknown },
): Promise<boolean>

Returns true when the context declares an entities config and the corresponding _chunk_entities table physically exists. Use this to guard entity tool registration at runtime.

Table-name helpers

ExuluReadApi.getTableName(contextId: string): string
ExuluReadApi.getChunksTableName(contextId: string): string
ExuluReadApi.getEntitiesTableName(contextId: string): string
ExuluReadApi.getChunkEntitiesTableName(contextId: string): string

Return the Postgres table names used by the given context. Useful when building custom queries directly against the database.

Example

import { ExuluReadApi, postgresClient } from "@exulu/backend";

// Read all chunks for two known items, respecting RBAC
const chunks = await ExuluReadApi.authorizedRead(
  productDocsContext,
  req.user,
  req.user.role?.id ?? "viewer",
  { itemIds: ["item-abc", "item-def"] },
);

// Stream chunk content to the calling agent
for (const chunk of chunks) {
  console.log(chunk.item_name, chunk.chunk_index, chunk.chunk_content);
}

Resolve table names for a custom Knex query:

const { db } = await postgresClient();
const chunksTable = ExuluReadApi.getChunksTableName("product_docs");

const recent = await db(chunksTable)
  .where("chunk_index", 0)
  .orderBy("createdAt", "desc")
  .limit(10);

Notes

authorizedRead always applies RBAC via applyAccessControl on the items alias — this gate cannot be bypassed through opts.
Results are ordered by (chunks.source, chunks.chunk_index) — stable page order for items with multiple chunks.
embedQuery routes through the same resolveEmbedder path as the ingestion pipeline, so LiteLLM cost attribution applies.

ExuluContext — introduction: ExuluContext.search() for relevance-ranked retrieval.
VectorSearchChunkResult: shape of the returned chunk rows.

Start

Tutorials

Recipes

Core classes

Reference

API surface

ExuluReadApi.authorizedRead

ExuluReadApi.embedQuery

ExuluReadApi.entitiesAvailable

Table-name helpers

Example

Notes

​API surface

​ExuluReadApi.authorizedRead

​ExuluReadApi.embedQuery

​ExuluReadApi.entitiesAvailable

​Table-name helpers

​Example

​Notes

​Related

API surface

ExuluReadApi.authorizedRead

ExuluReadApi.embedQuery

ExuluReadApi.entitiesAvailable

Table-name helpers

Example

Notes

Related