Clarify behavior in docstring (#2628)

docs/mkdocs.yml

@@ -225,6 +225,7 @@ nav:
               - cloud/deployment/setup.md
               - cloud/deployment/setup_pyproject.md
               - cloud/deployment/setup_javascript.md
+              - cloud/deployment/semantic_search.md
               - cloud/deployment/custom_docker.md
               - cloud/deployment/test_locally.md
               - cloud/deployment/graph_rebuild.md

libs/checkpoint-postgres/langgraph/store/postgres/aio.py

@@ -72,6 +72,8 @@ class AsyncPostgresStore(AsyncBatchedBaseStore, BasePostgresStore[_ainternal.Con
             # Store documents
             await store.aput(("docs",), "doc1", {"text": "Python tutorial"})
             await store.aput(("docs",), "doc2", {"text": "TypeScript guide"})
+            # Don't index the following
+            await store.aput(("docs",), "doc3", {"text": "Other guide"}, index=False)
 
             # Search by similarity
             results = await store.asearch(("docs",), query="python programming")

libs/checkpoint-postgres/langgraph/store/postgres/base.py

@@ -569,6 +569,7 @@ class PostgresStore(BaseStore, BasePostgresStore[_pg_internal.Conn]):
         # Store documents
         store.put(("docs",), "doc1", {"text": "Python tutorial"})
         store.put(("docs",), "doc2", {"text": "TypeScript guide"})
+        store.put(("docs",), "doc2", {"text": "Other guide"}, index=False) # don't index
 
         # Search by similarity
         results = store.search(("docs",), query="python programming")

libs/checkpoint/langgraph/store/base/__init__.py

@@ -557,10 +557,15 @@ async def aembed_texts(texts: list[str]) -> list[list[float]]:
     """Fields to extract text from for embedding generation.
     
     Controls which parts of stored items are embedded for semantic search. Follows JSON path syntax:
-    - ["$"] (default): Embeds the entire JSON object as one vector
-    - ["field1", "field2"]: Embeds specific top-level fields
-    - ["parent.child"]: Embeds nested fields using dot notation
-    - ["array[*].field"]: Embeds field from each array element separately
+
+        - ["$"]: Embeds the entire JSON object as one vector  (default)
+        - ["field1", "field2"]: Embeds specific top-level fields
+        - ["parent.child"]: Embeds nested fields using dot notation
+        - ["array[*].field"]: Embeds field from each array element separately
+    
+    Note:
+        You can always override this behavior when storing an item using the
+        `index` parameter in the `put` or `aput` operations.
     
     ???+ example "Examples"
         ```python
@@ -706,15 +711,18 @@ def put(
             index: Controls how the item's fields are indexed for search:
 
                 - None (default): Use `fields` you configured when creating the store (if any)
+                    If you do not initialize the store with indexing capabilities,
+                    the `index` parameter will be ignored
                 - False: Disable indexing for this item
                 - list[str]: List of field paths to index, supporting:
                     - Nested fields: "metadata.title"
                     - Array access: "chapters[*].content" (each indexed separately)
                     - Specific indices: "authors[0].name"
 
         Note:
-            Indexing capabilities depend on your store implementation.
-            Some implementations may support only a subset of indexing features.
+            Indexing support depends on your store implementation.
+            If you do not initialize the store with indexing capabilities,
+            the `index` parameter will be ignored.
 
         ???+ example "Examples"
             Store item. Indexing depends on how you configure the store.
@@ -890,15 +898,18 @@ async def aput(
             index: Controls how the item's fields are indexed for search:
 
                 - None (default): Use `fields` you configured when creating the store (if any)
+                    If you do not initialize the store with indexing capabilities,
+                    the `index` parameter will be ignored
                 - False: Disable indexing for this item
                 - list[str]: List of field paths to index, supporting:
                     - Nested fields: "metadata.title"
                     - Array access: "chapters[*].content" (each indexed separately)
                     - Specific indices: "authors[0].name"
 
         Note:
-            Indexing capabilities depend on your store implementation.
-            Some implementations may support only a subset of indexing features.
+            Indexing support depends on your store implementation.
+            If you do not initialize the store with indexing capabilities,
+            the `index` parameter will be ignored.
 
         ???+ example "Examples"
             Store item. Indexing depends on how you configure the store.