feat: [TPUF-1097] tpuf: return failed IDs for conditional writes

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 11
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/turbopuffer-benesch%2Fturbopuffer-fa6433a17c7e89ab3329d6f31204ec4996d187b199096b76c09665c73003515c.yml
-openapi_spec_hash: 507a79825cddda3b68915b007d262851
-config_hash: 96def6365ccbb9b4d87d665602519568
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/turbopuffer-benesch%2Fturbopuffer-d496b79de3c2f3c601206f699e7d13fa74f0afed31f73fa94d08bb195b79f6c2.yml
+openapi_spec_hash: 8d838304a3f379497edb054f8f427153
+config_hash: e0aa4ce6d5a9a6e326ad47865d970b74

README.md

@@ -13,8 +13,8 @@ It is generated with [Stainless](https://www.stainless.com/).
 
 Use the Turbopuffer MCP Server to enable AI assistants to interact with this API, allowing them to explore endpoints, make test requests, and use documentation to help integrate this SDK into your application.
 
-[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=%40turbopuffer%2Fturbopuffer-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkB0dXJib3B1ZmZlci90dXJib3B1ZmZlci1tY3AiXX0)
-[![Install in VS Code](https://img.shields.io/badge/_-Add_to_VS_Code-blue?style=for-the-badge&logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIGZpbGw9Im5vbmUiIHZpZXdCb3g9IjAgMCA0MCA0MCI+PHBhdGggZmlsbD0iI0VFRSIgZmlsbC1ydWxlPSJldmVub2RkIiBkPSJNMzAuMjM1IDM5Ljg4NGEyLjQ5MSAyLjQ5MSAwIDAgMS0xLjc4MS0uNzNMMTIuNyAyNC43OGwtMy40NiAyLjYyNC0zLjQwNiAyLjU4MmExLjY2NSAxLjY2NSAwIDAgMS0xLjA4Mi4zMzggMS42NjQgMS42NjQgMCAwIDEtMS4wNDYtLjQzMWwtMi4yLTJhMS42NjYgMS42NjYgMCAwIDEgMC0yLjQ2M0w3LjQ1OCAyMCA0LjY3IDE3LjQ1MyAxLjUwNyAxNC41N2ExLjY2NSAxLjY2NSAwIDAgMSAwLTIuNDYzbDIuMi0yYTEuNjY1IDEuNjY1IDAgMCAxIDIuMTMtLjA5N2w2Ljg2MyA1LjIwOUwyOC40NTIuODQ0YTIuNDg4IDIuNDg4IDAgMCAxIDEuODQxLS43MjljLjM1MS4wMDkuNjk5LjA5MSAxLjAxOS4yNDVsOC4yMzYgMy45NjFhMi41IDIuNSAwIDAgMSAxLjQxNSAyLjI1M3YuMDk5LS4wNDVWMzMuMzd2LS4wNDUuMDk1YTIuNTAxIDIuNTAxIDAgMCAxLTEuNDE2IDIuMjU3bC04LjIzNSAzLjk2MWEyLjQ5MiAyLjQ5MiAwIDAgMS0xLjA3Ny4yNDZabS43MTYtMjguOTQ3LTExLjk0OCA5LjA2MiAxMS45NTIgOS4wNjUtLjAwNC0xOC4xMjdaIi8+PC9zdmc+)](https://vscode.stainless.com/mcp/%7B%22name%22%3A%22%40turbopuffer%2Fturbopuffer-mcp%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40turbopuffer%2Fturbopuffer-mcp%22%5D%7D)
+[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=%40turbopuffer%2Fturbopuffer-mcp&config=eyJuYW1lIjoiQHR1cmJvcHVmZmVyL3R1cmJvcHVmZmVyLW1jcCIsInRyYW5zcG9ydCI6InNzZSIsInVybCI6Imh0dHBzOi8vdHVyYm9wdWZmZXIuc3RsbWNwLmNvbS9zc2UifQ)
+[![Install in VS Code](https://img.shields.io/badge/_-Add_to_VS_Code-blue?style=for-the-badge&logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIGZpbGw9Im5vbmUiIHZpZXdCb3g9IjAgMCA0MCA0MCI+PHBhdGggZmlsbD0iI0VFRSIgZmlsbC1ydWxlPSJldmVub2RkIiBkPSJNMzAuMjM1IDM5Ljg4NGEyLjQ5MSAyLjQ5MSAwIDAgMS0xLjc4MS0uNzNMMTIuNyAyNC43OGwtMy40NiAyLjYyNC0zLjQwNiAyLjU4MmExLjY2NSAxLjY2NSAwIDAgMS0xLjA4Mi4zMzggMS42NjQgMS42NjQgMCAwIDEtMS4wNDYtLjQzMWwtMi4yLTJhMS42NjYgMS42NjYgMCAwIDEgMC0yLjQ2M0w3LjQ1OCAyMCA0LjY3IDE3LjQ1MyAxLjUwNyAxNC41N2ExLjY2NSAxLjY2NSAwIDAgMSAwLTIuNDYzbDIuMi0yYTEuNjY1IDEuNjY1IDAgMCAxIDIuMTMtLjA5N2w2Ljg2MyA1LjIwOUwyOC40NTIuODQ0YTIuNDg4IDIuNDg4IDAgMCAxIDEuODQxLS43MjljLjM1MS4wMDkuNjk5LjA5MSAxLjAxOS4yNDVsOC4yMzYgMy45NjFhMi41IDIuNSAwIDAgMSAxLjQxNSAyLjI1M3YuMDk5LS4wNDVWMzMuMzd2LS4wNDUuMDk1YTIuNTAxIDIuNTAxIDAgMCAxLTEuNDE2IDIuMjU3bC04LjIzNSAzLjk2MWEyLjQ5MiAyLjQ5MiAwIDAgMS0xLjA3Ny4yNDZabS43MTYtMjguOTQ3LTExLjk0OCA5LjA2MiAxMS45NTIgOS4wNjUtLjAwNC0xOC4xMjdaIi8+PC9zdmc+)](https://vscode.stainless.com/mcp/%7B%22name%22%3A%22%40turbopuffer%2Fturbopuffer-mcp%22%2C%22type%22%3A%22sse%22%2C%22url%22%3A%22https%3A%2F%2Fturbopuffer.stlmcp.com%2Fsse%22%7D)
 
 > Note: You may need to set environment variables in your MCP client.
 

src/turbopuffer/resources/namespaces.py

@@ -556,6 +556,7 @@ def write(
         patch_columns: ColumnsParam | Omit = omit,
         patch_condition: Filter | Omit = omit,
         patch_rows: Iterable[RowParam] | Omit = omit,
+        return_affected_ids: bool | Omit = omit,
         schema: Dict[str, AttributeSchemaParam] | Omit = omit,
         upsert_columns: ColumnsParam | Omit = omit,
         upsert_condition: Filter | Omit = omit,
@@ -596,6 +597,10 @@ def write(
           patch_condition: A condition evaluated against the current value of each document targeted by a
               patch write. Only documents that pass the condition are patched.
 
+          return_affected_ids: If true, return the IDs of affected rows (deleted, patched, upserted) in the
+              response. For filtered and conditional writes, only IDs for writes that
+              succeeded will be included.
+
           schema: The schema of the attributes attached to the documents.
 
           upsert_columns: A list of documents in columnar format. Each key is a column name, mapped to an
@@ -633,6 +638,7 @@ def write(
                     "patch_columns": patch_columns,
                     "patch_condition": patch_condition,
                     "patch_rows": patch_rows,
+                    "return_affected_ids": return_affected_ids,
                     "schema": schema,
                     "upsert_columns": upsert_columns,
                     "upsert_condition": upsert_condition,
@@ -1152,6 +1158,7 @@ async def write(
         patch_columns: ColumnsParam | Omit = omit,
         patch_condition: object | Omit = omit,
         patch_rows: Iterable[RowParam] | Omit = omit,
+        return_affected_ids: bool | Omit = omit,
         schema: Dict[str, AttributeSchemaParam] | Omit = omit,
         upsert_columns: ColumnsParam | Omit = omit,
         upsert_condition: object | Omit = omit,
@@ -1192,6 +1199,10 @@ async def write(
           patch_condition: A condition evaluated against the current value of each document targeted by a
               patch write. Only documents that pass the condition are patched.
 
+          return_affected_ids: If true, return the IDs of affected rows (deleted, patched, upserted) in the
+              response. For filtered and conditional writes, only IDs for writes that
+              succeeded will be included.
+
           schema: The schema of the attributes attached to the documents.
 
           upsert_columns: A list of documents in columnar format. Each key is a column name, mapped to an
@@ -1229,6 +1240,7 @@ async def write(
                     "patch_columns": patch_columns,
                     "patch_condition": patch_condition,
                     "patch_rows": patch_rows,
+                    "return_affected_ids": return_affected_ids,
                     "schema": schema,
                     "upsert_columns": upsert_columns,
                     "upsert_condition": upsert_condition,

src/turbopuffer/types/namespace_write_params.py

@@ -72,6 +72,13 @@ class NamespaceWriteParams(TypedDict, total=False):
 
     patch_rows: Iterable[RowParam]
 
+    return_affected_ids: bool
+    """
+    If true, return the IDs of affected rows (deleted, patched, upserted) in the
+    response. For filtered and conditional writes, only IDs for writes that
+    succeeded will be included.
+    """
+
     schema: Dict[str, AttributeSchemaParam]
     """The schema of the attributes attached to the documents."""
 

src/turbopuffer/types/namespace_write_response.py

@@ -1,8 +1,9 @@
 # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-from typing import Optional
+from typing import List, Optional
 from typing_extensions import Literal
 
+from .id import ID
 from .._models import BaseModel
 from .write_billing import WriteBilling
 
@@ -24,6 +25,20 @@ class NamespaceWriteResponse(BaseModel):
     status: Literal["OK"]
     """The status of the request."""
 
+    deleted_ids: Optional[List[ID]] = None
+    """The IDs of documents that were deleted.
+
+    Only included when `return_affected_ids` is true and at least one document was
+    deleted.
+    """
+
+    patched_ids: Optional[List[ID]] = None
+    """The IDs of documents that were patched.
+
+    Only included when `return_affected_ids` is true and at least one document was
+    patched.
+    """
+
     rows_deleted: Optional[int] = None
     """The number of rows deleted by the write request."""
 
@@ -35,3 +50,10 @@ class NamespaceWriteResponse(BaseModel):
 
     rows_upserted: Optional[int] = None
     """The number of rows upserted by the write request."""
+
+    upserted_ids: Optional[List[ID]] = None
+    """The IDs of documents that were upserted.
+
+    Only included when `return_affected_ids` is true and at least one document was
+    upserted.
+    """

tests/api_resources/test_namespaces.py

@@ -442,6 +442,7 @@ def test_method_write_with_all_params(self, client: Turbopuffer) -> None:
                     "vector": [0],
                 }
             ],
+            return_affected_ids=True,
             schema={"foo": "string"},
             upsert_columns={
                 "id": ["182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"],
@@ -911,6 +912,7 @@ async def test_method_write_with_all_params(self, async_client: AsyncTurbopuffer
                     "vector": [0],
                 }
             ],
+            return_affected_ids=True,
             schema={"foo": "string"},
             upsert_columns={
                 "id": ["182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"],