update documentation for searching and scrolling apis

Author: fupelaqu

README.md

@@ -99,7 +99,7 @@ val searchResult = client.search(SQLQuery("SELECT * FROM users WHERE age > 25"))
 case class Product(id: String, name: String, price: Double, category: String, obsolete: Boolean)
 
 // Scroll through large datasets
-val obsoleteProducts: Source[Product, NotUsed] = client.scrollAs[Product](
+val obsoleteProducts: Source[Product, NotUsed] = client.scrollAsUnchecked[Product](
   """
     |SELECT uuid AS id, name, price, category, outdated AS obsolete FROM products WHERE outdated = true
     |""".stripMargin

documentation/client/scroll.md

@@ -90,7 +90,7 @@ def scroll(
 )(implicit system: ActorSystem): Source[(Map[String, Any], ScrollMetrics), NotUsed]
 
 // Typed scroll source (automatic deserialization)
-def scrollAs[T](
+def scrollAsUnchecked[T](
   sql: SQLQuery,
   config: ScrollConfig = ScrollConfig()
 )(implicit
@@ -394,7 +394,7 @@ val query = SQLQuery(
 )
 
 // Scroll with automatic type conversion
-client.scrollAs[Product](query).runWith(Sink.foreach { case (product, metrics) =>
+client.scrollAsUnchecked[Product](query).runWith(Sink.foreach { case (product, metrics) =>
   println(s"Product: ${product.name} - $${product.price}")
   println(s"Progress: ${metrics.totalDocuments} products")
 })
@@ -407,7 +407,7 @@ client.scrollAs[Product](query).runWith(Sink.foreach { case (product, metrics) =
 ```scala
 // Collect all products
 val allProducts: Future[Seq[Product]] = 
-  client.scrollAs[Product](query)
+  client.scrollAsUnchecked[Product](query)
     .map(_._1) // Extract product, discard metrics
     .runWith(Sink.seq)
 
@@ -425,7 +425,7 @@ allProducts.foreach { products =>
 
 ```scala
 // Filter expensive products during streaming
-client.scrollAs[Product](query)
+client.scrollAsUnchecked[Product](query)
   .filter { case (product, _) => product.price > 500 }
   .map(_._1) // Extract product
   .runWith(Sink.seq)
@@ -444,6 +444,30 @@ client.scrollAs[Product](query)
 ```scala
 case class ProductSummary(name: String, value: Double)
 
+client.scrollAsUnchecked[Product](query)
+  .map { case (product, _) =>
+    ProductSummary(
+      name = product.name,
+      value = product.price * product.stock
+    )
+  }
+  .runWith(Sink.seq)
+  .foreach { summaries =>
+    val totalValue = summaries.map(_.value).sum
+    println(f"Total inventory value: $$${totalValue}%,.2f")
+  }
+```
+
+### Validating Query at compile-time
+
+```scala
+val query = 
+  """
+    SELECT id, name, price, category, stock
+    FROM products
+    WHERE category = 'electronics'
+  """
+
 client.scrollAs[Product](query)
   .map { case (product, _) =>
     ProductSummary(
@@ -456,8 +480,12 @@ client.scrollAs[Product](query)
     val totalValue = summaries.map(_.value).sum
     println(f"Total inventory value: $$${totalValue}%,.2f")
   }
+)
+
 ```
 
+📖 **[Full SQL Validation Documentation](../sql/validation.md)**
+
 ---
 
 ## Metrics and Monitoring
@@ -807,7 +835,7 @@ def commitBatch(size: Int): Future[Unit] = {
 case class RawProduct(id: String, name: String, price: Double)
 case class EnrichedProduct(id: String, name: String, price: Double, category: String, tags: Seq[String])
 
-client.scrollAs[RawProduct](query)
+client.scrollAsUnchecked[RawProduct](query)
   .mapAsync(parallelism = 4) { case (raw, _) =>
     // Enrich each product
     enrichProduct(raw)
@@ -904,7 +932,7 @@ case class Statistics(
   )
 }
 
-client.scrollAs[Product](query)
+client.scrollAsUnchecked[Product](query)
   .map(_._1.price) // Extract prices
   .fold(Statistics())(_ update _)
   .runWith(Sink.head)
@@ -922,7 +950,7 @@ client.scrollAs[Product](query)
 ### Conditional Processing
 
 ```scala
-client.scrollAs[Product](query)
+client.scrollAsUnchecked[Product](query)
   .mapAsync(parallelism = 4) { case (product, _) =>
     product.category match {
       case "electronics" => processElectronics(product)
@@ -1003,7 +1031,7 @@ class ScrollApiSpec extends AsyncFlatSpec with Matchers {
 
     // Test
     query = SQLQuery(query = s"SELECT id, value FROM $testIndex")
-    results <- client.scrollAs[TestDoc](query).map(_._1).runWith(Sink.seq)
+    results <- client.scrollAsUnchecked[TestDoc](query).map(_._1).runWith(Sink.seq)
 
     // Assertions
     _ = {
@@ -1259,7 +1287,7 @@ client.scroll(query).map { case (doc, _) =>
 
 // ✅ GOOD: Automatic type conversion
 implicit val formats: Formats = DefaultFormats
-client.scrollAs[Product](query)
+client.scrollAsUnchecked[Product](query)
   .map(_._1)
   .runWith(Sink.seq)
 ```
@@ -1556,7 +1584,7 @@ case class ValidationResult(
 )
 
 def validateData(query: SQLQuery): Future[ValidationResult] = {
-  client.scrollAs[Product](query)
+  client.scrollAsUnchecked[Product](query)
     .map(_._1)
     .runWith(Sink.fold(ValidationResult(0, 0, Seq.empty)) { (result, product) =>
       if (isValid(product)) {
@@ -1598,7 +1626,7 @@ case class CategoryStats(
 )
 
 def aggregateByCategory(query: SQLQuery): Future[Map[String, CategoryStats]] = {
-  client.scrollAs[Product](query)
+  client.scrollAsUnchecked[Product](query)
     .map(_._1)
     .runWith(Sink.fold(Map.empty[String, CategoryStats]) { (stats, product) =>
       val current = stats.getOrElse(
@@ -1645,7 +1673,7 @@ case class EnrichedOrder(
 )
 
 def transformOrders(query: SQLQuery): Future[Seq[EnrichedOrder]] = {
-  client.scrollAs[RawOrder](query)
+  client.scrollAsUnchecked[RawOrder](query)
     .map(_._1)
     .mapAsync(parallelism = 4) { order =>
       // Enrich with customer data

documentation/client/search.md

@@ -14,10 +14,12 @@
   - [singleSearchAsync](#singlesearchasync)
   - [multiSearchAsync](#multisearchasync)
 - [Search with Type Conversion](#search-with-type-conversion)
+  - [searchAsUnchecked](#searchasunchecked)
   - [searchAs](#searchas)
   - [singleSearchAs](#singlesearchas)
   - [multisearchAs](#multisearchas)
 - [Asynchronous Search with Type Conversion](#asynchronous-search-with-type-conversion)
+  - [searchAsyncAsUnchecked](#searchasyncasunchecked)
   - [searchAsyncAs](#searchasyncas)
   - [singleSearchAsyncAs](#singlesearchasyncas)
   - [multiSearchAsyncAs](#multisearchasyncas)
@@ -611,7 +613,7 @@ client.multiSearchAsync(queries, Map.empty, Map.empty).foreach {
 
 ## Search with Type Conversion
 
-### searchAs
+### searchAsUnchecked
 
 Searches and automatically converts results to typed entities using an SQL query.
 
@@ -706,6 +708,29 @@ val result: ElasticResult[List[EnrichedProduct]] = for {
 
 ---
 
+### searchAs
+
+Searches and automatically converts results to typed entities using an SQL query [validated at compile-time](../sql/validation.md).
+
+**Signature:**
+
+```scala
+def searchAs[U](
+  query: String
+)(implicit m: Manifest[U], formats: Formats): ElasticResult[Seq[U]]
+```
+
+**Parameters:**
+- `query` - SQL query
+- `m` - Implicit Manifest for type information
+- `formats` - Implicit JSON serialization formats
+
+**Returns:**
+- `ElasticSuccess[Seq[U]]` with typed entities
+- `ElasticFailure` with conversion or search errors
+
+---
+
 ### singleSearchAs
 
 Searches and converts results to typed entities using an Elasticsearch query.
@@ -818,7 +843,7 @@ client.multisearchAs[Product](queries, Map.empty, Map.empty) match {
 
 ## Asynchronous Search with Type Conversion
 
-### searchAsyncAs
+### searchAsyncAsUnchecked
 
 Asynchronously searches and converts results to typed entities.
 
@@ -880,6 +905,23 @@ Future.sequence(futures).map { results =>
   }
 }
 ```
+---
+
+### searchAsyncAs
+
+Asynchronously searches and converts results to typed entities using an SQL query [validated at compile-time](../sql/validation.md).
+
+**Signature:**
+
+```scala
+def searchAsyncAs[U](
+  query: String
+)(implicit
+  m: Manifest[U],
+  ec: ExecutionContext,
+  formats: Formats
+): Future[ElasticResult[Seq[U]]]
+```
 
 ---