From d062e2dc8de05701a63c476a4048560f60b2f10c Mon Sep 17 00:00:00 2001
From: Sh1nku <42642351+Sh1nku@users.noreply.github.com>
Date: Tue, 10 Dec 2024 11:42:44 +0100
Subject: [PATCH] Add additional examples for grouping and facets

---
 wrappers/python/solrstice/models.pyi | 66 ++++++++++++++++++++++++++++
 1 file changed, 66 insertions(+)

diff --git a/wrappers/python/solrstice/models.pyi b/wrappers/python/solrstice/models.pyi
index 748d78e..a992260 100644
--- a/wrappers/python/solrstice/models.pyi
+++ b/wrappers/python/solrstice/models.pyi
@@ -131,12 +131,34 @@ class SolrGroupResult:
         """
         Gets the field results form a group query
         :return: List of group field results
+
+        >>> from solrstice import GroupingComponent, SelectQuery, SolrServerContext, AsyncSolrCloudClient
+        >>> client = AsyncSolrCloudClient(SolrServerContext('localhost:8983'))
+        >>> async def field_result() -> None:
+        ...     group_builder = GroupingComponent(fields=["age"], limit=10)
+        ...     select_builder = SelectQuery(fq=["age:[* TO *]"], grouping=group_builder)
+        ...     groups = (await client.select(select_builder, "example_collection")).get_groups()
+        ...     age_group = groups["age"]
+        ...     docs = age_group.get_field_result()
+
         """
 
     def get_query_result(self) -> Optional["SolrDocsResponse"]:
         """
         Gets the query result from a group query
         :return: Query result
+
+        >>> from solrstice import GroupingComponent, SelectQuery, SolrServerContext, AsyncSolrCloudClient
+        >>> client = AsyncSolrCloudClient(SolrServerContext('localhost:8983'))
+        >>> async def group_query_result() -> None:
+        ...     group_builder = GroupingComponent(queries=["age:[0 TO 59]", "age:[60 TO *]"], limit=10)
+        ...     select_builder = SelectQuery(fq=["age:[* TO *]"], grouping=group_builder)
+        ...     groups = (await client.select(select_builder, "example_collection")).get_groups()
+        ...     age_group = groups["age:[0 TO 59]"]
+        ...     group = age_group.get_query_result()
+        ...     assert group is not None
+        ...     docs = group.get_docs()
+
         """
 
     def get_simple_result(self) -> Optional["SolrDocsResponse"]:
@@ -166,18 +188,62 @@ class SolrJsonFacetResponse:
         """
         Get the buckets for this facet
         :return: A list of buckets
+
+        >>> from solrstice import AsyncSolrCloudClient, SolrServerContext, SelectQuery, JsonFacetComponent, JsonTermsFacet
+        >>> client = AsyncSolrCloudClient(SolrServerContext('localhost:8983'))
+        >>> async def json_facet_buckets() -> None:
+        ...     select_builder = SelectQuery(
+        ...         json_facet=JsonFacetComponent(facets={"age": JsonTermsFacet("age")})
+        ...     )
+        ...     response = await client.select(select_builder, "example_collection")
+        ...     facets = response.get_json_facets()
+        ...     assert facets is not None
+        ...     age_buckets = facets.get_nested_facets()["age"].get_buckets()
+        ...     assert len(age_buckets) == 3
+
         """
 
     def get_flat_facets(self) -> Dict[str, Any]:
         """
         Get stat counts for this facet
         :return: A dictionary of stat counts
+
+        >>> from solrstice import JsonFacetComponent, JsonStatFacet, SelectQuery, SolrServerContext, AsyncSolrCloudClient
+        >>> client = AsyncSolrCloudClient(SolrServerContext('localhost:8983'))
+        >>> async def json_flat_facets() -> None:
+        ...     select_builder = SelectQuery(
+        ...         json_facet=JsonFacetComponent(
+        ...             facets={"total_people": JsonStatFacet("sum(count)")}
+        ...         )
+        ...     )
+        ...     response = await client.select(select_builder, "example_collection")
+        ...     facets = response.get_json_facets()
+        ...     assert facets is not None
+        ...     total_people = facets.get_flat_facets()["total_people"]
+        ...     assert total_people == 1000
+
         """
 
     def get_nested_facets(self) -> Dict[str, "SolrJsonFacetResponse"]:
         """
         Get the nested facets for this facet
         :return: A dictionary of nested facets
+
+        >>> from solrstice import JsonFacetComponent, JsonQueryFacet, SelectQuery, SolrServerContext, AsyncSolrCloudClient
+        >>> async def main() -> None:
+        ...     client = AsyncSolrCloudClient(SolrServerContext('localhost:8983'))
+        ...     select_builder = SelectQuery(
+        ...         json_facet=JsonFacetComponent(
+        ...             facets={"below_60": JsonQueryFacet("age:[0 TO 59]")}
+        ...         )
+        ...     )
+        ...     response = await client.select(select_builder, "example_collection")
+        ...     facets = response.get_json_facets()
+        ...     assert facets is not None
+        ...     below_60 = facets.get_nested_facets().get("below_60")
+        ...     assert below_60 is not None
+        ...     assert below_60.get_count() == 4
+
         """
 
     def get_count(self) -> Optional[int]: