!function(){function t(t){document.documentElement.setAttribute("data-theme",t)}var e=function(){var t=null;try{t=new URLSearchParams(window.location.search).get("docusaurus-theme")}catch(t){}return t}()||function(){var t=null;try{t=localStorage.getItem("theme")}catch(t){}return t}();t(null!==e?e:"light")}(),document.documentElement.setAttribute("data-announcement-bar-initially-dismissed",function(){try{return"true"===localStorage.getItem("docusaurus.announcement.dismiss")}catch(t){}return!1}())

[Skip to main content](#__docusaurus_skipToContent_fallback)

LangChain v0.2 is coming soon! Preview the new docs [here](/v0.2/docs/introduction/).

[

![🦜️🔗 Langchain](/v0.1/img/brand/wordmark.png)![🦜️🔗 Langchain](/v0.1/img/brand/wordmark-dark.png)

](/v0.1/)[Docs](/v0.1/docs/get_started/introduction/)[Use cases](/v0.1/docs/use_cases/)[Integrations](/v0.1/docs/integrations/platforms/)[API Reference](https://api.js.langchain.com)

[More](#)

*   [People](/v0.1/docs/people/)
*   [Community](/v0.1/docs/community/)
*   [Tutorials](/v0.1/docs/additional_resources/tutorials/)
*   [Contributing](/v0.1/docs/contributing/)

[v0.1](#)

*   [v0.2](https://js.langchain.com/v0.2/docs/introduction)
*   [v0.1](/v0.1/docs/get_started/introduction/)

[🦜🔗](#)

*   [LangSmith](https://smith.langchain.com)
*   [LangSmith Docs](https://docs.smith.langchain.com)
*   [LangChain Hub](https://smith.langchain.com/hub)
*   [LangServe](https://github.com/langchain-ai/langserve)
*   [Python Docs](https://python.langchain.com/)

[Chat](https://chatjs.langchain.com)[](https://github.com/langchain-ai/langchainjs)

Search

*   [Get started](/v0.1/docs/get_started/)
    
    *   [Introduction](/v0.1/docs/get_started/introduction/)
    *   [Installation](/v0.1/docs/get_started/installation/)
    *   [Quickstart](/v0.1/docs/get_started/quickstart/)
*   [LangChain Expression Language](/v0.1/docs/expression_language/)
    
    *   [Get started](/v0.1/docs/expression_language/get_started/)
    *   [Why use LCEL?](/v0.1/docs/expression_language/why/)
    *   [Interface](/v0.1/docs/expression_language/interface/)
    *   [Streaming](/v0.1/docs/expression_language/streaming/)
    *   [How to](/v0.1/docs/expression_language/how_to/routing/)
        
    *   [Cookbook](/v0.1/docs/expression_language/cookbook/)
        
    *   [LangChain Expression Language (LCEL)](/v0.1/docs/expression_language/)
*   [Modules](/v0.1/docs/modules/)
    
    *   [Model I/O](/v0.1/docs/modules/model_io/)
        
    *   [Retrieval](/v0.1/docs/modules/data_connection/)
        
        *   [Document loaders](/v0.1/docs/modules/data_connection/document_loaders/)
            
        *   [Text Splitters](/v0.1/docs/modules/data_connection/document_transformers/)
            
        *   [Retrievers](/v0.1/docs/modules/data_connection/retrievers/)
            
        *   [Retrieval](/v0.1/docs/modules/data_connection/)
        *   [Text embedding models](/v0.1/docs/modules/data_connection/text_embedding/)
            
        *   [Vector stores](/v0.1/docs/modules/data_connection/vectorstores/)
            
        *   [Indexing](/v0.1/docs/modules/data_connection/indexing/)
        *   [Experimental](/v0.1/docs/modules/data_connection/experimental/multimodal_embeddings/google_vertex_ai/)
            
    *   [Chains](/v0.1/docs/modules/chains/)
    *   [Agents](/v0.1/docs/modules/agents/)
        
    *   [More](/v0.1/docs/modules/memory/)
        
*   [Security](/v0.1/docs/security/)
*   [Guides](/v0.1/docs/guides/)
    
*   [Ecosystem](/v0.1/docs/ecosystem/)
    
*   [LangGraph](/v0.1/docs/langgraph/)
*   * * *
    

*   [](/v0.1/)
*   [Modules](/v0.1/docs/modules/)
*   [Retrieval](/v0.1/docs/modules/data_connection/)
*   Indexing

On this page

Indexing
========

Here, we will look at a basic indexing workflow using the LangChain indexing API.

The indexing API lets you load and keep in sync documents from any source into a vector store. Specifically, it helps:

*   Avoid writing duplicated content into the vector store
*   Avoid re-writing unchanged content
*   Avoid re-computing embeddings over unchanged content

All of which should save you time and money, as well as improve your vector search results.

Crucially, the indexing API will work even with documents that have gone through several transformation steps (e.g., via text chunking) with respect to the original source documents.

How it works[​](#how-it-works "Direct link to How it works")
------------------------------------------------------------

LangChain indexing makes use of a record manager (`RecordManager`) that keeps track of document writes into the vector store.

When indexing content, hashes are computed for each document, and the following information is stored in the record manager:

*   the document hash (hash of both page content and metadata)
*   write time
*   the source ID - each document should include information in its metadata to allow us to determine the ultimate source of this document

Deletion Modes[​](#deletion-modes "Direct link to Deletion Modes")
------------------------------------------------------------------

When indexing documents into a vector store, it's possible that some existing documents in the vector store should be deleted. In certain situations you may want to remove any existing documents that are derived from the same sources as the new documents being indexed. In others you may want to delete all existing documents wholesale. The indexing API deletion modes let you pick the behavior you want:

Cleanup Mode

De-Duplicates Content

Parallelizable

Cleans Up Deleted Source Docs

Cleans Up Mutations of Source Docs and/or Derived Docs

Clean Up Timing

None

✅

✅

❌

❌

\-

Incremental

✅

✅

❌

✅

Continuously

Full

✅

❌

✅

✅

At end of indexing

`None` does not do any automatic clean up, allowing the user to manually do clean up of old content.

`incremental` and `full` offer the following automated clean up:

*   If the content of the source document or derived documents has changed, both `incremental` or `full` modes will clean up (delete) previous versions of the content.
*   If the source document has been deleted (meaning it is not included in the documents currently being indexed), the full cleanup mode will delete it from the vector store correctly, but the `incremental` mode will not.

When content is mutated (e.g., the source PDF file was revised) there will be a period of time during indexing when both the new and old versions may be returned to the user. This happens after the new content was written, but before the old version was deleted.

*   `incremental` indexing minimizes this period of time as it is able to do clean up continuously, as it writes.
*   `full` mode does the clean up after all batches have been written.

Requirements[​](#requirements "Direct link to Requirements")
------------------------------------------------------------

1.  Do not use with a store that has been pre-populated with content independently of the indexing API, as the record manager will not know that records have been inserted previously.
2.  Only works with LangChain `vectorstore`'s that support: a). document addition by id (`addDocuments` method with ids argument) b). delete by id (delete method with ids argument)

Compatible Vectorstores: [`PGVector`](/v0.1/docs/integrations/vectorstores/pgvector/), [`Chroma`](/v0.1/docs/integrations/vectorstores/chroma/), [`CloudflareVectorize`](/v0.1/docs/integrations/vectorstores/cloudflare_vectorize/), [`ElasticVectorSearch`](/v0.1/docs/integrations/vectorstores/elasticsearch/), [`FAISS`](/v0.1/docs/integrations/vectorstores/faiss/), [`MomentoVectorIndex`](/v0.1/docs/integrations/vectorstores/momento_vector_index/), [`Pinecone`](/v0.1/docs/integrations/vectorstores/pinecone/), [`SupabaseVectorStore`](/v0.1/docs/integrations/vectorstores/supabase/), [`VercelPostgresVectorStore`](/v0.1/docs/integrations/vectorstores/vercel_postgres/), [`Weaviate`](/v0.1/docs/integrations/vectorstores/weaviate/), [`Xata`](/v0.1/docs/integrations/vectorstores/xata/)

Caution[​](#caution "Direct link to Caution")
---------------------------------------------

The record manager relies on a time-based mechanism to determine what content can be cleaned up (when using `full` or `incremental` cleanup modes).

If two tasks run back-to-back, and the first task finishes before the clock time changes, then the second task may not be able to clean up content.

This is unlikely to be an issue in actual settings for the following reasons:

1.  The `RecordManager` uses higher resolution timestamps.
2.  The data would need to change between the first and the second tasks runs, which becomes unlikely if the time interval between the tasks is small.
3.  Indexing tasks typically take more than a few ms.

Quickstart[​](#quickstart "Direct link to Quickstart")
------------------------------------------------------

    import { PostgresRecordManager } from "@langchain/community/indexes/postgres";import { index } from "langchain/indexes";import { PGVectorStore } from "@langchain/community/vectorstores/pgvector";import { PoolConfig } from "pg";import { OpenAIEmbeddings } from "@langchain/openai";import { CharacterTextSplitter } from "langchain/text_splitter";import { BaseDocumentLoader } from "langchain/document_loaders/base";// First, follow set-up instructions at// https://js.langchain.com/docs/modules/indexes/vector_stores/integrations/pgvectorconst config = {  postgresConnectionOptions: {    type: "postgres",    host: "127.0.0.1",    port: 5432,    user: "myuser",    password: "ChangeMe",    database: "api",  } as PoolConfig,  tableName: "testlangchain",  columns: {    idColumnName: "id",    vectorColumnName: "vector",    contentColumnName: "content",    metadataColumnName: "metadata",  },};const vectorStore = await PGVectorStore.initialize(  new OpenAIEmbeddings(),  config);// Create a new record managerconst recordManagerConfig = {  postgresConnectionOptions: {    type: "postgres",    host: "127.0.0.1",    port: 5432,    user: "myuser",    password: "ChangeMe",    database: "api",  } as PoolConfig,  tableName: "upsertion_records",};const recordManager = new PostgresRecordManager(  "test_namespace",  recordManagerConfig);// Create the schema if it doesn't existawait recordManager.createSchema();// Index some documentsconst doc1 = {  pageContent: "kitty",  metadata: { source: "kitty.txt" },};const doc2 = {  pageContent: "doggy",  metadata: { source: "doggy.txt" },};/** * Hacky helper method to clear content. See the `full` mode section to to understand why it works. */async function clear() {  await index({    docsSource: [],    recordManager,    vectorStore,    options: {      cleanup: "full",      sourceIdKey: "source",    },  });}// No cleanupawait clear();// This mode does not do automatic clean up of old versions of content; however, it still takes care of content de-duplication.console.log(  await index({    docsSource: [doc1, doc1, doc1, doc1, doc1, doc1],    recordManager,    vectorStore,    options: {      cleanup: undefined,      sourceIdKey: "source",    },  }));/*    {        numAdded: 1,        numUpdated: 0,        numDeleted: 0,        numSkipped: 0,    }*/await clear();console.log(  await index({    docsSource: [doc1, doc2],    recordManager,    vectorStore,    options: {      cleanup: undefined,      sourceIdKey: "source",    },  }));/*    {        numAdded: 2,        numUpdated: 0,        numDeleted: 0,        numSkipped: 0,    }*/// Second time around all content will be skippedconsole.log(  await index({    docsSource: [doc1, doc2],    recordManager,    vectorStore,    options: {      cleanup: undefined,      sourceIdKey: "source",    },  }));/*    {        numAdded: 0,        numUpdated: 0,        numDeleted: 0,        numSkipped: 2,    }*/// Updated content will be added, but old won't be deletedconst doc1Updated = {  pageContent: "kitty updated",  metadata: { source: "kitty.txt" },};console.log(  await index({    docsSource: [doc1Updated, doc2],    recordManager,    vectorStore,    options: {      cleanup: undefined,      sourceIdKey: "source",    },  }));/*    {        numAdded: 1,        numUpdated: 0,        numDeleted: 0,        numSkipped: 1,    }*//*Resulting records in the database:    [        {            pageContent: "kitty",            metadata: { source: "kitty.txt" },        },        {            pageContent: "doggy",            metadata: { source: "doggy.txt" },        },        {            pageContent: "kitty updated",            metadata: { source: "kitty.txt" },        }    ]*/// Incremental modeawait clear();console.log(  await index({    docsSource: [doc1, doc2],    recordManager,    vectorStore,    options: {      cleanup: "incremental",      sourceIdKey: "source",    },  }));/*    {        numAdded: 2,        numUpdated: 0,        numDeleted: 0,        numSkipped: 0,    }*/// Indexing again should result in both documents getting skipped – also skipping the embedding operation!console.log(  await index({    docsSource: [doc1, doc2],    recordManager,    vectorStore,    options: {      cleanup: "incremental",      sourceIdKey: "source",    },  }));/*    {        numAdded: 0,        numUpdated: 0,        numDeleted: 0,        numSkipped: 2,    }*/// If we provide no documents with incremental indexing mode, nothing will change.console.log(  await index({    docsSource: [],    recordManager,    vectorStore,    options: {      cleanup: "incremental",      sourceIdKey: "source",    },  }));/*    {        numAdded: 0,        numUpdated: 0,        numDeleted: 0,        numSkipped: 0,    }*/// If we mutate a document, the new version will be written and all old versions sharing the same source will be deleted.// This only affects the documents with the same source id!const changedDoc1 = {  pageContent: "kitty updated",  metadata: { source: "kitty.txt" },};console.log(  await index({    docsSource: [changedDoc1],    recordManager,    vectorStore,    options: {      cleanup: "incremental",      sourceIdKey: "source",    },  }));/*    {        numAdded: 1,        numUpdated: 0,        numDeleted: 1,        numSkipped: 0,    }*/// Full modeawait clear();// In full mode the user should pass the full universe of content that should be indexed into the indexing function.// Any documents that are not passed into the indexing function and are present in the vectorStore will be deleted!// This behavior is useful to handle deletions of source documents.const allDocs = [doc1, doc2];console.log(  await index({    docsSource: allDocs,    recordManager,    vectorStore,    options: {      cleanup: "full",      sourceIdKey: "source",    },  }));/*    {        numAdded: 2,        numUpdated: 0,        numDeleted: 0,        numSkipped: 0,    }*/// Say someone deleted the first doc:const doc2Only = [doc2];// Using full mode will clean up the deleted content as well.// This afffects all documents regardless of source id!console.log(  await index({    docsSource: doc2Only,    recordManager,    vectorStore,    options: {      cleanup: "full",      sourceIdKey: "source",    },  }));/*    {        numAdded: 0,        numUpdated: 0,        numDeleted: 1,        numSkipped: 1,    }*/await clear();const newDoc1 = {  pageContent: "kitty kitty kitty kitty kitty",  metadata: { source: "kitty.txt" },};const newDoc2 = {  pageContent: "doggy doggy the doggy",  metadata: { source: "doggy.txt" },};const splitter = new CharacterTextSplitter({  separator: "t",  keepSeparator: true,  chunkSize: 12,  chunkOverlap: 2,});const newDocs = await splitter.splitDocuments([newDoc1, newDoc2]);console.log(newDocs);/*[  {    pageContent: 'kitty kit',    metadata: {source: 'kitty.txt'}  },  {    pageContent: 'tty kitty ki',    metadata: {source: 'kitty.txt'}  },  {    pageContent: 'tty kitty',    metadata: {source: 'kitty.txt'},  },  {    pageContent: 'doggy doggy',    metadata: {source: 'doggy.txt'},  {    pageContent: 'the doggy',    metadata: {source: 'doggy.txt'},  }]*/console.log(  await index({    docsSource: newDocs,    recordManager,    vectorStore,    options: {      cleanup: "incremental",      sourceIdKey: "source",    },  }));/*{    numAdded: 5,    numUpdated: 0,    numDeleted: 0,    numSkipped: 0,}*/const changedDoggyDocs = [  {    pageContent: "woof woof",    metadata: { source: "doggy.txt" },  },  {    pageContent: "woof woof woof",    metadata: { source: "doggy.txt" },  },];console.log(  await index({    docsSource: changedDoggyDocs,    recordManager,    vectorStore,    options: {      cleanup: "incremental",      sourceIdKey: "source",    },  }));/*{    numAdded: 2,    numUpdated: 0,    numDeleted: 2,    numSkipped: 0,}*/// Usage with document loaders// Create a document loaderclass MyCustomDocumentLoader extends BaseDocumentLoader {  load() {    return Promise.resolve([      {        pageContent: "kitty",        metadata: { source: "kitty.txt" },      },      {        pageContent: "doggy",        metadata: { source: "doggy.txt" },      },    ]);  }}await clear();const loader = new MyCustomDocumentLoader();console.log(  await index({    docsSource: loader,    recordManager,    vectorStore,    options: {      cleanup: "incremental",      sourceIdKey: "source",    },  }));/*{    numAdded: 2,    numUpdated: 0,    numDeleted: 0,    numSkipped: 0,}*/// Closing resourcesawait recordManager.end();await vectorStore.end();

#### API Reference:

*   [PostgresRecordManager](https://api.js.langchain.com/classes/langchain_community_indexes_postgres.PostgresRecordManager.html) from `@langchain/community/indexes/postgres`
*   [index](https://api.js.langchain.com/functions/langchain_indexes.index.html) from `langchain/indexes`
*   [PGVectorStore](https://api.js.langchain.com/classes/langchain_community_vectorstores_pgvector.PGVectorStore.html) from `@langchain/community/vectorstores/pgvector`
*   [OpenAIEmbeddings](https://api.js.langchain.com/classes/langchain_openai.OpenAIEmbeddings.html) from `@langchain/openai`
*   [CharacterTextSplitter](https://api.js.langchain.com/classes/langchain_textsplitters.CharacterTextSplitter.html) from `langchain/text_splitter`
*   [BaseDocumentLoader](https://api.js.langchain.com/classes/langchain_document_loaders_base.BaseDocumentLoader.html) from `langchain/document_loaders/base`

* * *

#### Help us out by providing feedback on this documentation page:

[

Previous

Custom vectorstores

](/v0.1/docs/modules/data_connection/vectorstores/custom/)[

Next

Google Vertex AI

](/v0.1/docs/modules/data_connection/experimental/multimodal_embeddings/google_vertex_ai/)

*   [How it works](#how-it-works)
*   [Deletion Modes](#deletion-modes)
*   [Requirements](#requirements)
*   [Caution](#caution)
*   [Quickstart](#quickstart)

Community

*   [Discord](https://discord.gg/cU2adEyC7w)
*   [Twitter](https://twitter.com/LangChainAI)

GitHub

*   [Python](https://github.com/langchain-ai/langchain)
*   [JS/TS](https://github.com/langchain-ai/langchainjs)

More

*   [Homepage](https://langchain.com)
*   [Blog](https://blog.langchain.dev)

Copyright © 2024 LangChain, Inc.