Class PostgresStore

PostgreSQL implementation of the BaseStore interface. This is now a lightweight orchestrator that delegates to specialized modules.

Hierarchy (View Summary)

BaseStore
- PostgresStore

Index

Constructors

constructor

Methods

batch delete get getStats hybridSearch listNamespaces put search setup start stop sweepExpiredItems vectorSearch fromConnString

Constructors

constructor

new PostgresStore(config: PostgresStoreConfig): PostgresStore
Parameters
- config: PostgresStoreConfig
Returns PostgresStore
Overrides BaseStore.constructor
- Defined in checkpoint-postgres/src/store/index.ts:57

Methods

batch

batch<Op extends Operation[]>(operations: Op): Promise<OperationResults<Op>>
Execute multiple operations in a single batch.
Type Parameters
- Op extends Operation[]
Parameters
- operations: Op
Returns Promise<OperationResults<Op>>
Overrides BaseStore.batch
- Defined in checkpoint-postgres/src/store/index.ts:280

delete

delete(namespace: string[], key: string): Promise<void>
Delete an item by namespace and key.
Parameters
- namespace: string[]
- key: string
Returns Promise<void>
Overrides BaseStore.delete
- Defined in checkpoint-postgres/src/store/index.ts:126

get

get(namespace: string[], key: string): Promise<null | Item>
Get an item by namespace and key.
Parameters
- namespace: string[]
- key: string
Returns Promise<null | Item>
Overrides BaseStore.get
- Defined in checkpoint-postgres/src/store/index.ts:113

getStats

getStats(): Promise<
    {
        expiredItems: number;
        namespaceCount: number;
        newestItem: null
        | Date;
        oldestItem: null | Date;
        totalItems: number;
    },
>
Get statistics about the store.

Returns Promise<
    {
        expiredItems: number;
        namespaceCount: number;
        newestItem: null
        | Date;
        oldestItem: null | Date;
        totalItems: number;
    },
>
- Defined in checkpoint-postgres/src/store/index.ts:411

`Protected`hybridSearch

hybridSearch(
    namespacePrefix: string[],
    query: string,
    options?: {
        filter?: Record<string, unknown>;
        limit?: number;
        offset?: number;
        similarityThreshold?: number;
        vectorWeight?: number;
    },
): Promise<SearchItem[]>
Performs hybrid search combining vector similarity and text search.
Parameters
- namespacePrefix: string[]
  The namespace prefix to search within
- query: string
  The text query to search for
- options: {
      filter?: Record<string, unknown>;
      limit?: number;
      offset?: number;
      similarityThreshold?: number;
      vectorWeight?: number;
  } = {}
  Search options including filter, vector weight, and similarity threshold
Returns Promise<SearchItem[]>
Promise resolving to an array of search results with combined similarity scores
- Defined in checkpoint-postgres/src/store/index.ts:484

listNamespaces

listNamespaces(
    options?: {
        limit?: number;
        maxDepth?: number;
        offset?: number;
        prefix?: string[];
        suffix?: string[];
    },
): Promise<string[][]>
List namespaces with optional filtering.
Parameters
- options: {
      limit?: number;
      maxDepth?: number;
      offset?: number;
      prefix?: string[];
      suffix?: string[];
  } = {}
Returns Promise<string[][]>
Overrides BaseStore.listNamespaces
- Defined in checkpoint-postgres/src/store/index.ts:140

put

put(
    namespace: string[],
    key: string,
    value: Record<string, unknown>,
    index?: false | string[],
    options?: { ttl?: number },
): Promise<void>
Put an item with optional indexing configuration and TTL.
Parameters
- namespace: string[]
- key: string
- value: Record<string, unknown>
- Optionalindex: false | string[]
- Optionaloptions: { ttl?: number }
Returns Promise<void>
Overrides BaseStore.put
- Defined in checkpoint-postgres/src/store/index.ts:86

search

search(
    namespacePrefix: string[],
    options?: {
        distanceMetric?: "cosine" | "l2" | "inner_product";
        filter?: Record<
            string,
            null
            | string
            | number
            | boolean
            | FilterOperators,
        >;
        limit?: number;
        mode?: "text" | "vector" | "hybrid" | "auto";
        offset?: number;
        query?: string;
        refreshTtl?: boolean;
        similarityThreshold?: number;
        vectorWeight?: number;
    },
): Promise<SearchItem[]>
Search for items in the store with support for text search, vector search, and filtering.
Parameters
- namespacePrefix: string[]
  The namespace prefix to search within
- options: {
      distanceMetric?: "cosine" | "l2" | "inner_product";
      filter?: Record<string, null | string | number | boolean | FilterOperators>;
      limit?: number;
      mode?: "text" | "vector" | "hybrid" | "auto";
      offset?: number;
      query?: string;
      refreshTtl?: boolean;
      similarityThreshold?: number;
      vectorWeight?: number;
  } = {}
  Search options including search mode, filters, query text, and pagination
  - OptionaldistanceMetric?: "cosine" | "l2" | "inner_product"
    Distance metric for vector search.
    
    Default
    "cosine"
  - Optionalfilter?: Record<string, null | string | number | boolean | FilterOperators>
    Filter conditions with support for advanced operators.
  - Optionallimit?: number
    Maximum number of results to return.
    
    Default
    10
  - Optionalmode?: "text" | "vector" | "hybrid" | "auto"
    Search mode.
    
    Default
    "auto"
  - Optionaloffset?: number
    Number of results to skip for pagination.
    
    Default
    0
  - Optionalquery?: string
    Natural language search query.
  - OptionalrefreshTtl?: boolean
    Whether to refresh TTL for returned items.
  - OptionalsimilarityThreshold?: number
    Similarity threshold for vector search.
  - OptionalvectorWeight?: number
    Weight for vector search in hybrid mode.
    
    Default
    0.7
Returns Promise<SearchItem[]>
Promise resolving to an array of search results with optional similarity scores
Example
```
// Basic text search
const results = await store.search(["documents"], {
  query: "machine learning",
  mode: "text"
});

// Vector search
const results = await store.search(["documents"], {
  query: "machine learning",
  mode: "vector",
  similarityThreshold: 0.7
});

// Hybrid search (combining vector and text)
const results = await store.search(["documents"], {
  query: "machine learning",
  mode: "hybrid",
  vectorWeight: 0.7
});

// Filtered search
const results = await store.search(["products"], {
  filter: { category: "electronics", price: { $lt: 100 } }
});
```
Overrides BaseStore.search
- Defined in checkpoint-postgres/src/store/index.ts:543

setup

setup(): Promise<void>
Initialize the store by running migrations to create necessary tables and indexes.

Returns Promise<void>
- Defined in checkpoint-postgres/src/store/index.ts:200

start

start(): Promise<void>
Start the store. Calls setup() if ensureTables is true.

Returns Promise<void>
Overrides BaseStore.start
- Defined in checkpoint-postgres/src/store/index.ts:370

stop

stop(): Promise<void>
Stop the store and close all database connections.

Returns Promise<void>
Overrides BaseStore.stop
- Defined in checkpoint-postgres/src/store/index.ts:379

sweepExpiredItems

sweepExpiredItems(): Promise<number>
Manually sweep expired items from the store.

Returns Promise<number>
- Defined in checkpoint-postgres/src/store/index.ts:390

`Protected`vectorSearch

vectorSearch(
    namespacePrefix: string[],
    query: string,
    options?: {
        distanceMetric?: "cosine" | "l2" | "inner_product";
        filter?: Record<string, unknown>;
        limit?: number;
        offset?: number;
        similarityThreshold?: number;
    },
): Promise<SearchItem[]>
Performs vector similarity search using embeddings.
Parameters
- namespacePrefix: string[]
  The namespace prefix to search within
- query: string
  The text query to embed and search for similar items
- options: {
      distanceMetric?: "cosine" | "l2" | "inner_product";
      filter?: Record<string, unknown>;
      limit?: number;
      offset?: number;
      similarityThreshold?: number;
  } = {}
  Search options including filter, similarity threshold, and distance metric
Returns Promise<SearchItem[]>
Promise resolving to an array of search results with similarity scores
- Defined in checkpoint-postgres/src/store/index.ts:452

`Static`fromConnString

fromConnString(
connectionString: string,
options?: Omit<PostgresStoreConfig, "connectionOptions">,
): PostgresStore
Creates a PostgresStore instance from a connection string.
Parameters
- connectionString: string
- Optionaloptions: Omit<PostgresStoreConfig, "connectionOptions">
Returns PostgresStore
- Defined in checkpoint-postgres/src/store/index.ts:187

Class PostgresStore

Hierarchy (View Summary)

Index

Constructors

Methods

Constructors

constructor

Parameters

Returns PostgresStore

Methods

batch

Type Parameters

Parameters

Returns Promise<OperationResults<Op>>

delete

Parameters

Returns Promise<void>

get

Parameters

Returns Promise<null | Item>

getStats

Returns Promise< { expiredItems: number; namespaceCount: number; newestItem: null | Date; oldestItem: null | Date; totalItems: number; },>

ProtectedhybridSearch

Parameters

Returns Promise<SearchItem[]>

listNamespaces

Parameters

Returns Promise<string[][]>

put

Parameters

Returns Promise<void>

search

Parameters

OptionaldistanceMetric?: "cosine" | "l2" | "inner_product"

Default

Optionalfilter?: Record<string, null | string | number | boolean | FilterOperators>

Optionallimit?: number

Default

Optionalmode?: "text" | "vector" | "hybrid" | "auto"

Default

Optionaloffset?: number

Default

Optionalquery?: string

OptionalrefreshTtl?: boolean

OptionalsimilarityThreshold?: number

OptionalvectorWeight?: number

Default

Returns Promise<SearchItem[]>

Example

setup

Returns Promise<void>

start

Returns Promise<void>

stop

Returns Promise<void>

sweepExpiredItems

Returns Promise<number>

ProtectedvectorSearch

Parameters

Returns Promise<SearchItem[]>

StaticfromConnString

Parameters

Returns PostgresStore

Settings

On This Page

Returns Promise<
{
expiredItems: number;
namespaceCount: number;
newestItem: null
| Date;
oldestItem: null | Date;
totalItems: number;
},
>

`Protected`hybridSearch

`Optional`distanceMetric?: "cosine" | "l2" | "inner_product"

`Optional`filter?: Record<string, null | string | number | boolean | FilterOperators>

`Optional`limit?: number

`Optional`mode?: "text" | "vector" | "hybrid" | "auto"

`Optional`offset?: number

`Optional`query?: string

`Optional`refreshTtl?: boolean

`Optional`similarityThreshold?: number

`Optional`vectorWeight?: number

`Protected`vectorSearch

`Static`fromConnString