Update list examples (#827)

js/src/client.ts

@@ -2183,6 +2183,9 @@ export class Client {
     splits,
     inlineS3Urls,
     metadata,
+    limit,
+    offset,
+    filter,
   }: {
     datasetId?: string;
     datasetName?: string;
@@ -2191,6 +2194,9 @@ export class Client {
     splits?: string[];
     inlineS3Urls?: boolean;
     metadata?: KVMap;
+    limit?: number;
+    offset?: number;
+    filter?: string;
   } = {}): AsyncIterable<Example> {
     let datasetId_;
     if (datasetId !== undefined && datasetName !== undefined) {
@@ -2228,11 +2234,27 @@ export class Client {
       const serializedMetadata = JSON.stringify(metadata);
       params.append("metadata", serializedMetadata);
     }
+    if (limit !== undefined) {
+      params.append("limit", limit.toString());
+    }
+    if (offset !== undefined) {
+      params.append("offset", offset.toString());
+    }
+    if (filter !== undefined) {
+      params.append("filter", filter);
+    }
+    let i = 0;
     for await (const examples of this._getPaginated<Example>(
       "/examples",
       params
     )) {
-      yield* examples;
+      for (const example of examples) {
+        yield example;
+        i++;
+      }
+      if (limit !== undefined && i >= limit) {
+        break;
+      }
     }
   }
 

js/src/tests/client.int.test.ts

@@ -510,6 +510,22 @@ test.concurrent(
       client.listExamples({ datasetId: dataset.id })
     );
     expect(examplesList.length).toEqual(4);
+
+    const examplesListLimited = await toArray(
+      client.listExamples({ datasetId: dataset.id, limit: 2 })
+    );
+    expect(examplesListLimited.length).toEqual(2);
+
+    const examplesListOffset = await toArray(
+      client.listExamples({ datasetId: dataset.id, offset: 2 })
+    );
+    expect(examplesListOffset.length).toEqual(2);
+
+    const examplesListLimitedOffset = await toArray(
+      client.listExamples({ datasetId: dataset.id, limit: 1, offset: 2 })
+    );
+    expect(examplesListLimitedOffset.length).toEqual(1);
+
     await client.deleteExample(example.id);
     const examplesList2 = await toArray(
       client.listExamples({ datasetId: dataset.id })
@@ -583,6 +599,34 @@ test.concurrent(
     expect(examplesList3[0].metadata?.foo).toEqual("bar");
     expect(examplesList3[0].metadata?.baz).toEqual("qux");
 
+    examplesList3 = await toArray(
+      client.listExamples({
+        datasetId: dataset.id,
+        filter: 'exists(metadata, "baz")',
+      })
+    );
+    expect(examplesList3.length).toEqual(1);
+    expect(examplesList3[0].metadata?.foo).toEqual("bar");
+    expect(examplesList3[0].metadata?.baz).toEqual("qux");
+
+    examplesList3 = await toArray(
+      client.listExamples({
+        datasetId: dataset.id,
+        filter: 'has("metadata", \'{"foo": "bar"}\')',
+      })
+    );
+    expect(examplesList3.length).toEqual(1);
+    expect(examplesList3[0].metadata?.foo).toEqual("bar");
+    expect(examplesList3[0].metadata?.baz).toEqual("qux");
+
+    examplesList3 = await toArray(
+      client.listExamples({
+        datasetId: dataset.id,
+        filter: 'exists(metadata, "bazzz")',
+      })
+    );
+    expect(examplesList3.length).toEqual(0);
+
     examplesList3 = await toArray(
       client.listExamples({
         datasetId: dataset.id,

python/langsmith/client.py

@@ -3203,8 +3203,11 @@ def list_examples(
         as_of: Optional[Union[datetime.datetime, str]] = None,
         splits: Optional[Sequence[str]] = None,
         inline_s3_urls: bool = True,
+        *,
+        offset: int = 0,
         limit: Optional[int] = None,
         metadata: Optional[dict] = None,
+        filter: Optional[str] = None,
         **kwargs: Any,
     ) -> Iterator[ls_schemas.Example]:
         """Retrieve the example rows of the specified dataset.
@@ -3225,20 +3228,25 @@ def list_examples(
                 Returns examples only from the specified splits.
             inline_s3_urls (bool, optional): Whether to inline S3 URLs.
                 Defaults to True.
+            offset (int): The offset to start from. Defaults to 0.
             limit (int, optional): The maximum number of examples to return.
+            filter (str, optional): A structured fileter string to apply to
+                the examples.
 
         Yields:
             Example: The examples.
         """
         params: Dict[str, Any] = {
             **kwargs,
+            "offset": offset,
             "id": example_ids,
             "as_of": (
                 as_of.isoformat() if isinstance(as_of, datetime.datetime) else as_of
             ),
             "splits": splits,
             "inline_s3_urls": inline_s3_urls,
             "limit": min(limit, 100) if limit is not None else 100,
+            "filter": filter,
         }
         if metadata is not None:
             params["metadata"] = _dumps_json(metadata)

python/tests/integration_tests/test_client.py

@@ -128,6 +128,14 @@ def test_list_examples(langchain_client: Client) -> None:
     example_list = list(langchain_client.list_examples(dataset_id=dataset.id))
     assert len(example_list) == len(examples)
 
+    example_list = list(
+        langchain_client.list_examples(dataset_id=dataset.id, offset=1, limit=2)
+    )
+    assert len(example_list) == 2
+
+    example_list = list(langchain_client.list_examples(dataset_id=dataset.id, offset=1))
+    assert len(example_list) == len(examples) - 1
+
     example_list = list(
         langchain_client.list_examples(dataset_id=dataset.id, splits=["train"])
     )
@@ -202,6 +210,27 @@ def test_list_examples(langchain_client: Client) -> None:
     )
     assert len(example_list) == 0
 
+    example_list = list(
+        langchain_client.list_examples(
+            dataset_id=dataset.id, filter='exists(metadata, "baz")'
+        )
+    )
+    assert len(example_list) == 1
+
+    example_list = list(
+        langchain_client.list_examples(
+            dataset_id=dataset.id, filter='has("metadata", \'{"foo": "bar"}\')'
+        )
+    )
+    assert len(example_list) == 1
+
+    example_list = list(
+        langchain_client.list_examples(
+            dataset_id=dataset.id, filter='exists(metadata, "bazzz")'
+        )
+    )
+    assert len(example_list) == 0
+
     langchain_client.delete_dataset(dataset_id=dataset.id)