[sedona] branch master updated: [DOCS] Mention behavior of string returning functions (#1039)

[ji...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

jiayu pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/sedona.git


The following commit(s) were added to refs/heads/master by this push:
     new 16c797214 [DOCS] Mention behavior of string returning functions (#1039)
16c797214 is described below

commit 16c79721437b6618a1a458970247f7dd1e42f5f7
Author: Furqaanahmed Khan <46...@users.noreply.github.com>
AuthorDate: Thu Sep 28 16:02:16 2023 -0400

    [DOCS] Mention behavior of string returning functions (#1039)
---
 docs/api/sql/Raster-operators.md  | 25 ++++++++++++++++++++++++-
 docs/api/sql/Raster-visualizer.md | 27 +++++++++++++++++++++++++--
 2 files changed, 49 insertions(+), 3 deletions(-)

diff --git a/docs/api/sql/Raster-operators.md b/docs/api/sql/Raster-operators.md
index aba15f9f2..f2526a158 100644
--- a/docs/api/sql/Raster-operators.md
+++ b/docs/api/sql/Raster-operators.md
@@ -192,7 +192,30 @@ Provided band index 3 does not lie in the raster
 
 Introduction: Returns the georeference metadata of raster as a string in GDAL or ESRI format. Default is GDAL if not specified.
 
-Format: `RS_GeoReference(raster: Raster, format: String)`
+!!!note
+    If you are using `show()` to display the output, it will show special characters as escape sequences. To get the expected behavior use the following code:
+    
+    === "Scala"
+
+        ```scala
+        println(df.selectExpr("RS_GeoReference(rast)").sample(0.5).collect().mkString("\n"))
+        ```
+    
+    === "Java"
+    
+        ```java
+        System.out.println(String.join("\n", df.selectExpr("RS_GeoReference(rast)").sample(0.5).collect()))
+        ```
+    
+    === "Python"
+    
+        ```python
+        print("\n".join(df.selectExpr("RS_GeoReference(rast)").sample(0.5).collect()))
+        ```
+
+    The `sample()` function is only there to reduce the data sent to `collect()`, you may also use `filter()` if that's appropriate.
+
+Format: `RS_GeoReference(raster: Raster, format: String = "GDAL")`
 
 Since: `v1.5.0`
 
diff --git a/docs/api/sql/Raster-visualizer.md b/docs/api/sql/Raster-visualizer.md
index 39c2fdb13..3c7a594b4 100644
--- a/docs/api/sql/Raster-visualizer.md
+++ b/docs/api/sql/Raster-visualizer.md
@@ -68,6 +68,29 @@ RS_AsMatrix expects a raster, and optionally a band (default: 1) and postDecimal
 !!!Note
     If the provided raster has integral values, postDecimalPrecision (if any) is simply ignored and integers are printed in the resultant string
 
+!!!note
+    If you are using `show()` to display the output, it will show special characters as escape sequences. To get the expected behavior use the following code:
+
+    === "Scala"
+
+        ```scala
+        println(df.selectExpr("RS_AsMatrix(rast)").sample(0.5).collect().mkString("\n"))
+        ```
+    
+    === "Java"
+    
+        ```java
+        System.out.println(String.join("\n", df.selectExpr("RS_AsMatrix(rast)").sample(0.5).collect()))
+        ```
+    
+    === "Python"
+    
+        ```python
+        print("\n".join(df.selectExpr("RS_AsMatrix(rast)").sample(0.5).collect()))
+        ```
+
+    The `sample()` function is only there to reduce the data sent to `collect()`, you may also use `filter()` if that's appropriate.
+
 Format: 
 
 ```
@@ -80,7 +103,7 @@ Spark SQL Example:
 
 ```scala
 val inputDf = Seq(Seq(1, 3.333333, 4, 0.0001, 2.2222, 9, 10, 11.11111111, 3, 4, 5, 6)).toDF("band")
-inputDf.selectExpr("RS_AsMatrix(RS_AddBandFromArray(RS_MakeEmptyRaster(1, 'd', 4, 3, 0, 0, 1, -1, 0, 0, 0), band, 1, 0))").show()
+print(inputDf.selectExpr("RS_AsMatrix(RS_AddBandFromArray(RS_MakeEmptyRaster(1, 'd', 4, 3, 0, 0, 1, -1, 0, 0, 0), band, 1, 0))").sample(0.5).collect()(0))
 ```
 
 Output:
@@ -95,7 +118,7 @@ Spark SQL Example:
 
 ```scala
 val inputDf = Seq(Seq(1, 3, 4, 0, 2, 9, 10, 11, 3, 4, 5, 6)).toDF("band")
-inputDf.selectExpr("RS_AsMatrix(RS_AddBandFromArray(RS_MakeEmptyRaster(1, 'i', 4, 3, 0, 0, 1, -1, 0, 0, 0), band, 1, 0))").show()
+print(inputDf.selectExpr("RS_AsMatrix(RS_AddBandFromArray(RS_MakeEmptyRaster(1, 'i', 4, 3, 0, 0, 1, -1, 0, 0, 0), band, 1, 0))").sample(0.5).collect()(0))
 ```
 
 Output: