diff --git a/.github/workflows/deploy.yaml b/.github/workflows/deploy.yaml index 6010998..ff9cfe6 100644 --- a/.github/workflows/deploy.yaml +++ b/.github/workflows/deploy.yaml @@ -28,19 +28,19 @@ jobs: id: setup-pages - name: Checkout main - uses: actions/checkout@v3 + uses: actions/checkout@v4 with: ref: main path: main - name: Checkout upcoming - uses: actions/checkout@v3 + uses: actions/checkout@v4 with: ref: upcoming path: upcoming - name: Setup node - uses: actions/setup-node@v3 + uses: actions/setup-node@v4 with: node-version: '20.8' cache: yarn @@ -88,10 +88,10 @@ jobs: mv combined/lang_docs/tableauhyperapi-java-docs-* combined/lang_docs/java - name: Upload webpage artifact - uses: actions/upload-pages-artifact@v1 + uses: actions/upload-pages-artifact@v3 with: path: 'combined' - name: Deploy to GitHub Pages id: deployment - uses: actions/deploy-pages@v2 + uses: actions/deploy-pages@v4 diff --git a/.github/workflows/proof.yaml b/.github/workflows/proof.yaml index 35ca6ba..29a603d 100644 --- a/.github/workflows/proof.yaml +++ b/.github/workflows/proof.yaml @@ -14,10 +14,10 @@ jobs: runs-on: ubuntu-latest steps: - name: Checkout - uses: actions/checkout@v3 + uses: actions/checkout@v4 - name: Setup node - uses: actions/setup-node@v3 + uses: actions/setup-node@v4 with: node-version: '20.8' cache: yarn @@ -43,6 +43,6 @@ jobs: GITHUB_BASE_PATH: ${{ steps.setup-pages.outputs.base_path }} - name: Upload webpage artifact - uses: actions/upload-pages-artifact@v1 + uses: actions/upload-pages-artifact@v3 with: path: 'website/build' diff --git a/website/docs/guides/hyper_file/geodata.md b/website/docs/guides/hyper_file/geodata.md index bbe837f..607a3aa 100644 --- a/website/docs/guides/hyper_file/geodata.md +++ b/website/docs/guides/hyper_file/geodata.md @@ -1,32 +1,32 @@ -# Add Spatial Data to a Hyper File +# Add Geospatial Data to a Hyper File -Tableau supports spatial data (geography) in `.hyper` files. -This guide describes how you can use the Hyper API to add geography type data to the Hyper file. +Tableau supports geospatial data (`tableau.tabgeography`) in `.hyper` files. +This guide describes how you can use the Hyper API to add geospatial data to Hyper files. -The Hyper API does not directly accept Well-Known-Text for spatial data. -Instead you need to use a `CAST("column_as_text" AS GEOGRAPHY)` expression in the inserter to provide the spatial data as `text` strings. -Hyper API's inserter pushes the `CAST("column_as_text" AS GEOGRAPHY)` expression down to Hyper where the `text` strings are converted to spatial data. +The Hyper API does not directly accept Well-known text (WKT) for geospatial data. +Instead you need to use a `CAST("column_as_text" AS TABLEAU.TABGEOGRAPHY)` expression in the inserter to provide the geospatial data as `text` strings. +Hyper API's inserter pushes the `CAST("column_as_text" AS TABLEAU.TABGEOGRAPHY)` expression down to Hyper where the `text` strings are converted to geospatial data. -## Overview of inserting spatial data to a hyper file +## Overview of inserting geospatial data into a hyper file -The basic process for adding spatial data involves defining your inputs to Hyper APIs inserter and specifying how to convert the text strings to geography types using Hyper SQL expressions. Hyper APIs inserter pushes the expression down to Hyper to convert text string to spatial data on the fly during insertion +The basic process for adding geospatial data involves defining your inputs to Hyper APIs inserter and specifying how to convert the text strings to the `tableau.tabgeography` type using Hyper SQL expressions. Hyper APIs inserter pushes the expression down to Hyper to convert a text string to geospatial data on the fly during insertion. -When you add the text strings into the Hyper file, the text must be in the Well-Known-Text (WKT) format for geography data. The WKT is defined by the Open GIS Consortium, Inc, in the [*OpenGIS Simple Features Specification For SQL*](https://www.opengeospatial.org/standards/sfa). The types include **Point**, **MultiPoint**, **LineString**, **MultiLineString**, **Polygon**, and **MultiPolygon**. +When you add the text strings into the Hyper file, the text must be in the Well-known text (WKT) format for geospatial data. The WKT format is defined by the Open GIS Consortium, Inc, in the [*OpenGIS Simple Features Specification For SQL*](https://www.opengeospatial.org/standards/sfa). The types include **Point**, **MultiPoint**, **LineString**, **MultiLineString**, **Polygon**, and **MultiPolygon**. -## Create tables for text and spatial data +## Create tables for text and geospatial data -1. Define and create a table in the `.hyper` file to contain the `SqlType.geography()` data. This is the table that you will use in Tableau. For example, the following Python code snippet creates a table to hold location data. The table is called `Extract` and is in the `Extract` namespace (or schema) similar to Hyper files created with Tableau. +1. Define and create a table in the `.hyper` file with a `SqlType.tabgeography()` column. This is the table that you will use in Tableau. For example, the following Python code snippet creates a table to hold location data. The table is called `Extract` and is in the `Extract` namespace (or schema) similar to Hyper files created by Tableau. ```python connection.catalog.create_schema('Extract') geo_table = TableDefinition(TableName('Extract','Extract'), [ TableDefinition.Column('Name', SqlType.text(), nullability=NOT_NULLABLE), - TableDefinition.Column('Location', SqlType.geography(), nullability=NOT_NULLABLE), + TableDefinition.Column('Location', SqlType.tabgeography(), nullability=NOT_NULLABLE), ]) connection.catalog.create_table(geo_table) ``` -2. Define your inputs to the inserter as a List of `TableDefinition.Column` . This definition will be similar to the TableDefinition of `Extract` table created before except that the columns with `SqlType.geography()` will be specified as `SqlType.text()` type +2. Define your inputs to the inserter as a List of `TableDefinition.Column`. This definition will be similar to the TableDefinition of the `Extract` table created before except that the columns with `SqlType.tabgeography()` will be specified as `SqlType.text()` type ```python # Inserter definition contains the column definition for the values that are inserted @@ -36,21 +36,20 @@ When you add the text strings into the Hyper file, the text must be in the Well- TableDefinition.Column(name='Location_as_text', type=SqlType.text(), nullability=NOT_NULLABLE)] ``` -3. Specify the conversion of `SqlType.text()` to `SqlType.geography()` using `CAST` expression in `Inserter.ColumnMapping`. Specify all columns into which data is inserter in `Inserter.ColumnMapping` list. For columns that do not require any transformations provide only the names +3. Specify the conversion of `SqlType.text()` to `SqlType.tabgeography()` using `CAST` expression in `Inserter.ColumnMapping`. Specify all columns into which data is inserter in `Inserter.ColumnMapping` list. For columns that do not require any transformations provide only the names ```python column_mappings = [ 'Name', - Inserter.ColumnMapping('Location', f'CAST({escape_name("Location_as_text")} AS GEOGRAPHY)') + Inserter.ColumnMapping('Location', f'CAST({escape_name("Location_as_text")} AS TABLEAU.TABGEOGRAPHY)') ] ``` +## Insert the geospatial data as text (WKT) into the text table -## Insert the spatial data as text (WKT) into the text table +When you add the text data to the Hyper file, the text must be in the Well-known text (WKT) format for geospatial data, such as Point, Polygon, etc. For example, to specify location data, you would use `point(Longitude Latitude)`. -When you add the text data to the Hyper file, the text must be in the Well Known Text Format (WKT) format for geography data, such as Point, Polygon, etc. For example, to specify location data, you would use `point(Longitude Latitude)`. - -The following Python code example inserts two rows of data with location information into a table that is defined to hold geography data. +The following Python code example inserts two rows of data with location information into a table that is defined to hold geospatial data. ```python data_to_insert = [ @@ -63,12 +62,11 @@ with Inserter(connection, geo_table, column_mappings, inserter_definition = inse inserter.execute() ``` -Note if you have WKT data in a comma-separated value (CSV) file, you can use the [COPY](/docs/sql/command/copy_from) command to insert the data from a CSV file. The command automatically converts the WKT strings to the geography data type. For more information, see the [Example code using copy from CSV](#example-code-using-copy-from-csv) and the Help topic [Insert Data Directly from CSV Files](./insert_csv) and the CSV sample on GitHub, [hyper-api-samples](https://github.com/tableau/hyper-api-samples). +Note if you have WKT data in a comma-separated value (CSV) file, you can use the [COPY](/docs/sql/command/copy_from) command to insert the data from a CSV file. The command automatically converts the WKT strings to the `tableau.tabgeography` data type. For more information, see the [Example code using copy from CSV](#example-code-using-copy-from-csv) and the Help topic [Insert Data Directly from CSV Files](./insert_csv) and the CSV sample on GitHub, [hyper-api-samples](https://github.com/tableau/hyper-api-samples). ## Example code using the Inserter -The following example Python code illustrates how you can create a `.hyper` file that contains location (`geography`) information by using expressions in the Inserter. - +The following example Python code illustrates how you can create a `.hyper` file that contains location (`tableau.tabgeography`) information by using expressions in the Inserter. ```python from tableauhyperapi import Connection, HyperProcess, SqlType, TableDefinition, \ @@ -76,12 +74,12 @@ from tableauhyperapi import Connection, HyperProcess, SqlType, TableDefinition, with HyperProcess(Telemetry.SEND_USAGE_DATA_TO_TABLEAU, 'myapp' ) as hyper: - with Connection(hyper.endpoint, 'TrivialExample_geo.hyper', CreateMode.CREATE_AND_REPLACE) as connection: - # Create geography table + with Connection(hyper.endpoint, 'GeospatialExample.hyper', CreateMode.CREATE_AND_REPLACE) as connection: + # Create a table with a `tableau.tabgeography` column connection.catalog.create_schema('Extract') geo_table = TableDefinition(TableName('Extract','Extract'), [ TableDefinition.Column('Name', SqlType.text(), nullability=NOT_NULLABLE), - TableDefinition.Column('Location', SqlType.geography(), nullability=NOT_NULLABLE), + TableDefinition.Column('Location', SqlType.tabgeography(), nullability=NOT_NULLABLE), ]) print("The geo_table is defined.") connection.catalog.create_table(geo_table) @@ -93,15 +91,15 @@ with HyperProcess(Telemetry.SEND_USAGE_DATA_TO_TABLEAU, 'myapp' ) as hyper: TableDefinition.Column(name='Location_as_text', type=SqlType.text(), nullability=NOT_NULLABLE)] # Column 'Name' is inserted into "Extract"."Extract" as-is. - # Column 'Location' in "Extract"."Extract" of geography type is computed from Column 'Location_as_text' of text type - # using the expression 'CAST("Location_as_text") AS GEOGRAPHY'. + # Column 'Location' in "Extract"."Extract" of `tableau.tabgeography` type is computed from Column 'Location_as_text' of `text` type + # using the expression 'CAST("Location_as_text") AS TABLEAU.TABGEOGRAPHY'. # Inserter.ColumnMapping is used for mapping the CAST expression to Column 'Location'. column_mappings = [ 'Name', - Inserter.ColumnMapping('Location', f'CAST({escape_name("Location_as_text")} AS GEOGRAPHY)') + Inserter.ColumnMapping('Location', f'CAST({escape_name("Location_as_text")} AS TABLEAU.TABGEOGRAPHY)') ] - # Format the data as well-known text (WKT) + # Format the data as Well-known text (WKT) data_to_insert = [ [ 'Seattle', "point(-122.338083 47.647528)" ], [ 'Munich' , "point(11.584329 48.139257)" ] @@ -116,9 +114,9 @@ with HyperProcess(Telemetry.SEND_USAGE_DATA_TO_TABLEAU, 'myapp' ) as hyper: ## Example code using copy from CSV -When you copy the text data from a CSV file to the Hyper file, the text data is converted to geography data. Just as with the Inserter, the data must be in the Well Known Text Format (WKT) format for geography data, such as Point, Polygon, etc. For example, to specify location data, you would use `point(Longitude Latitude)`. +When you copy the text data from a CSV file to the Hyper file, the text data is converted to geospatial data. Just as with the Inserter, the data must be in the Well-known text (WKT) format for geospatial data, such as Point, Polygon, etc. For example, to specify location data, you would use `point(Longitude Latitude)`. -The following Python code example copies two rows of data from a CSV file into a table that is defined to hold geography data. The location data is in a CSV file (`locations.csv`) that looks like the following: +The following Python code example copies two rows of data from a CSV file into a table that is defined to hold geospatial data. The location data is in a CSV file (`locations.csv`) that looks like the following: ```csv title=locations.csv Name, Location @@ -130,16 +128,16 @@ Munich , point(11.584329 48.139257) from tableauhyperapi import Connection, HyperProcess, SqlType, TableDefinition, \ escape_string_literal, escape_name, NOT_NULLABLE, Telemetry, Inserter, CreateMode, TableName -# CSV file that contains, +# CSV file that contains location data in Well-known text (WKT) format path_to_csv = "locations.csv" with HyperProcess(Telemetry.SEND_USAGE_DATA_TO_TABLEAU, 'myapp' ) as hyper: - with Connection(hyper.endpoint, 'TrivialExample_geo_csv.hyper', CreateMode.CREATE_AND_REPLACE) as connection: - # Create geography table + with Connection(hyper.endpoint, 'GeospatialFromCSVExample.hyper', CreateMode.CREATE_AND_REPLACE) as connection: + # Create a table with a `tableau.tabgeography` column connection.catalog.create_schema('Extract') - geo_table = TableDefinition(TableName('Extract','Extract'), [ + geo_table = TableDefinition(TableName('Extract','Extract'), [ TableDefinition.Column('Name', SqlType.text(), nullability=NOT_NULLABLE), - TableDefinition.Column('Location', SqlType.geography(), nullability=NOT_NULLABLE)]) + TableDefinition.Column('Location', SqlType.tabgeography(), nullability=NOT_NULLABLE)]) connection.catalog.create_table(geo_table) # Load all rows into the geo_table from the CSV file. diff --git a/website/docs/releases.md b/website/docs/releases.md index 49b29a0..6ae3660 100644 --- a/website/docs/releases.md +++ b/website/docs/releases.md @@ -24,6 +24,19 @@ In case you are wondering why all our releases start with `0.0`, read [this FAQ ::: +### 0.0.21408 [Feb 13 2025] + +* The `geography` type has been renamed to `tableau.tabgeography` and the geospatial functions have been moved to the `tableau` namespace. + * Existing Hyper files will continue to work; however, SQL queries and HAPI programs will need to be adjusted. + * For example, use `tableau.geo_make_point` in SQL queries instead of just `geo_make_point`. + * Use `SqlType.tabgeography()` in Python and Java, and `SqlType::tabgeography()` in C++. + * The plain `geography` type and all geospatial functions outside the `tableau` namespace are deprecated and will be removed in the near future. + * See [Geographic Functions](/docs/sql/scalar_func/geography) and [Add Geospatial Data to a Hyper File](/docs/guides/hyper_file/geodata) for more information. +* IANA released version 2024a of the Time Zone Database. Hyper’s time zone information is updated accordingly. Noteworthy changes: + * Paraguay adopts permanent -03 starting spring 2024. + * Improve historical data for Mexico, Mongolia, Philippines, and Portugal. +* Update syntax for [`ARRAY` literals](./sql/datatype/array.md) and fixed bugs with quoting and escaping of text arrays. + ### 0.0.21200 [Jan 17 2025] * Support for Microsoft Azure Blob Storage using [`azure_location`](./sql/external/location.md#microsoft-azure-blob-storage) was added. @@ -359,8 +372,8 @@ Noteworthy changes in the Time Zone Database: * Hyper now adjusts the resulting interval from a timestamp subtraction so that 24-hour time periods are represented as days. * Hyper now supports +/-13 and +/-14 as timezone offsets. * Python: The most commonly used Hyper API types now have `__repr__()` methods and will return a string representation of the object when printed, making interactive exploring of the Hyper API more fun. -* Improved handling of spatial types: - * Parsing GEOGRAPHY values from well-known text (WKT) format automatically adjusts the order of vertices in polygons. +* Improved handling of geospatial types: + * Parsing GEOGRAPHY values from Well-known text (WKT) format automatically adjusts the order of vertices in polygons. * During WKT parsing, additional vertices may be added to more closely resemble the original shape specified in the WKT. ### 0.0.12514 [April 7, 2021] @@ -425,10 +438,10 @@ Noteworthy changes in the Time Zone Database: ### 0.0.11074 [June 24, 2020] -* Adds several SQL functions for managing spatial data: +* Adds several SQL functions for managing geospatial data: * For creating geography objects (`geo_make_point` and `geo_make_line`). * For performing calculations on geography objects (`geo_distance` and `geo_buffer`). - * For manipulating the vertex order of polygons in geography objects (`geo_auto_vertex_order` and `geo_invert_vertex_order`). These functions can be used to address problems (for example, with spatial joins or to automatically zoom) where data comes from a source that uses a different winding order for polygons than the one used by Tableau. In Tableau, the interior of the polygon is considered to be on the left of the path drawn by points of the polygon ring. + * For manipulating the vertex order of polygons in geography objects (`geo_auto_vertex_order` and `geo_invert_vertex_order`). These functions can be used to address problems (for example, with geospatial joins or to automatically zoom) where data comes from a source that uses a different winding order for polygons than the one used by Tableau. In Tableau, the interior of the polygon is considered to be on the left of the path drawn by points of the polygon ring. * See [Geographic Functions](/docs/sql/scalar_func/geography) for more information. * Prepared queries gained support for parallelized execution. See [PREPARE](/docs/sql/command/prepare) and [EXECUTE](/docs/sql/command/execute) for more information on prepared queries in Hyper. * Java: Fixed crashes that could occur when inserting more than 16 MB of data into a table. @@ -460,7 +473,7 @@ Noteworthy changes in the Time Zone Database: * The Hyper API `Inserter` class now allows SQL expressions to compute or transform data on the fly during insertion. -* The Hyper API `Inserter` class now allows inserting Well-Known-Text (WKT) into `Geography` columns. You can use the `CAST` expression to transform WKT data to the `Geography` type and provide WKT data as a string to the `Inserter` class. For more information, see [Add Spatial Data to a Hyper File](/docs/guides/hyper_file/geodata). +* The Hyper API `Inserter` class now allows inserting Well-known text (WKT) into `Geography` columns. You can use the `CAST` expression to transform WKT data to the `Geography` type and provide WKT data as a string to the `Inserter` class. For more information, see [Add Geospatial Data to a Hyper File](/docs/guides/hyper_file/geodata). * Documented the available settings that can be passed to the `HyperProcess` and `Connection` constructors. See [Settings](/docs/hyper-api/hyper_process#passingprocesssettings). diff --git a/website/docs/sql/datatype/array.md b/website/docs/sql/datatype/array.md index 0c140e3..17f75af 100644 --- a/website/docs/sql/datatype/array.md +++ b/website/docs/sql/datatype/array.md @@ -26,10 +26,10 @@ Arrays can be created in two ways: - Using the type constructor syntax ```sql > select array[1,2,3]; - {1,2,3} + [1,2,3] > select array['one','two','three']; - {one,two,three} + ["one","two","three"] ``` The constructor syntax consists of the keyword `array` followed by a comma-separated list of element SQL values surrounded by square brackets `[...]`. @@ -39,22 +39,24 @@ Arrays can be created in two ways: - Using a [cast](../scalar_func/conversion.md) from string data ```sql - > select '{1,2,3}'::array(integer); - {1,2,3} + > select '[1,2,3]'::array(integer); + [1,2,3] - > select '{one,two,three}'::array(text); - {one,two,three} + > select '[one,two,three]'::array(text); + ["one","two","three"] ``` - An array string literal consists of a comma-separated list of element literals surrounded by curly braces `{...}`. + An array string literal consists of a comma-separated list of element literals surrounded by square brackets `[...]`. The element literal syntax is identical to that of the respective atomic type. Note that for string array types (such as, e.g., `array(text)`), any upper- or lower-case variant of the element literal `null` will be parsed as a `null` value. To specify the string `null`, the element literal must be escaped using double quotes, like so: ```sql - > select '{null, "null"}'::array(text) - {NULL,null} # A null element, followed by the string 'null' + > select '[null, "null"]'::array(text) + [NULL,"null"] # A null element, followed by the string 'null' ``` + +When outputting an array of text types, every non-null element is quoted. ## Element Types and Nullability @@ -70,18 +72,18 @@ The following four options all represent different types in Hyper: |Type|array nullable?|elements nullable?| possible values| |---|---|---|---| -|`array(integer)`|✅|✅|`{}`,`{1,2,3}`,`{1,2,null}`, `null`| -|`array(integer not null)`|✅|❌|`{}`,`{1,2,3}`,`null`| -|`array(integer) not null`|❌|✅|`{}`,`{1,2,3}`,`{1,2,null}`| -|`array(integer not null) not null`|❌|❌|`{}`,`{1,2,3}`| +|`array(integer)`|✅|✅|`[]`,`[1,2,3]`,`[1,2,null]`, `null`| +|`array(integer not null)`|✅|❌|`[]`,`[1,2,3]`,`null`| +|`array(integer) not null`|❌|✅|`[]`,`[1,2,3]`,`[1,2,null]`| +|`array(integer not null) not null`|❌|❌|`[]`,`[1,2,3]`| The inner nullability of an array type can be changed by casting, using the conventional [cast syntax](../scalar_func/conversion.md): ```sql # nullable to non-nullable -> select ('{1,2,3}'::array(integer))::array(integer not null) +> select ('[1,2,3]'::array(integer))::array(integer not null) # non-nullable to nullable -> select ('{1,2,3}'::array(integer not null))::array(integer) +> select ('[1,2,3]'::array(integer not null))::array(integer) ``` A cast from a non-nullable element type to its nullable counterpart always succeeds. @@ -92,6 +94,11 @@ Casts across element types (e.g. from `array(integer not null)` to `array(bigint Non-nullable element types use less memory and enable optimizations for certain array operations. Users are therefore advised to use the most "restrictive" element type possible, given the use case at hand. ::: +:::note +Hyper used curly braces `{...}` to represent arrays as string literals up to (and including) version 0.0.21200. In those versions, it also tried to avoid quoting every element of a text array when it did not contain special characters. +The new syntax uses square brackets `[...]` and always quotes text elements, which more closely resembles the JSON array syntax. +::: + ## Limitations Arrays are subject to the following limitations: diff --git a/website/docs/sql/datatype/index.md b/website/docs/sql/datatype/index.md index 3c77bec..8fb2ff0 100644 --- a/website/docs/sql/datatype/index.md +++ b/website/docs/sql/datatype/index.md @@ -29,7 +29,7 @@ Name|Aliases|Description `TIME [ WITHOUT TIME ZONE ]`||time of day (no time zone) `TIMESTAMP [ WITHOUT TIME ZONE ]`||date and time (no time zone) `TIMESTAMP WITH TIME ZONE`|`TIMESTAMPTZ`|date and time, including time zone -`GEOGRAPHY`||a geography object +`TABLEAU.TABGEOGRAPHY`||a Tableau geography value :::note Persisting `NUMERIC`s with a precision greater than 18 requires at least [database version 3](/docs/hyper-api/hyper_process#version-3). diff --git a/website/docs/sql/scalar_func/arrays.md b/website/docs/sql/scalar_func/arrays.md index 00d2d88..e485501 100644 --- a/website/docs/sql/scalar_func/arrays.md +++ b/website/docs/sql/scalar_func/arrays.md @@ -12,7 +12,7 @@ Signature|Description|Example ---|---|--- array(T)**[**int**]** → `T`| Returns the n-th element of the array (1-indexed). | `(array[1,2,3])[1]` → `1` array(T)**[**int**:**int**]** → `T` | Returns the subarray within the given boundes (1-indexed, inclusive). |`(array[1,2,3])[2:3]` → `{2,3}` | -**array_length(**array**)** → `int` | Returns the length of the array. | `array_length(array[1,2,3])` → `3` +**array_length(**array**)** → `int` | Returns the length of the array. | `array_length(array[1,2,3])` → `3`
`array_length(array[])` → `0` **array_to_string(**array, text [, text]**)**| Converts the array into a textual representation, with the given element separator and (optional) null indicator. | `array_to_string(array[1,2,3], ';')` → `1;2;3`
`array_to_string(array[3,2,1,null], '⏰', '🎉')` → `3⏰2⏰1⏰🎉` **array_contains(**array, value**)**| Checks if a given value is contained within the array. | `array_contains(array[1,3,4], 3)` → `true`
`array_contains(array[1,3,4], 2)` → `false` **array_position(**array, value**)**| Returns the index of the first occurrence of `value` inside `array`. Comparisons are done using `IS NOT DISTINCT FROM` semantics, so it is possible to search for `NULL`. Returns `NULL` if the element is not found. | `array_position(array[1,3,4,3], 3)` → `2`
`array_contains(array[1,3,4,3], 2)` → `NULL` diff --git a/website/docs/sql/scalar_func/geography.md b/website/docs/sql/scalar_func/geography.md index 315a3d7..8698b00 100644 --- a/website/docs/sql/scalar_func/geography.md +++ b/website/docs/sql/scalar_func/geography.md @@ -1,64 +1,64 @@ # Geographic Functions Geographical functions operate on geographic input, like points, lines -or polygons. The built-in general-purpose geographic functions are -listed in below. +or polygons. The built-in geographic functions for Tableau geography +values are listed below. -## Geography functions +## Tableau geography functions Function|Description ---|---|--- -`geo_make_point(latitude double, longitude double)` → `geography(point)`|Creates a point with coordinates `latitude` and `longitude` -`geo_make_line(a geography(point), b geography(point))` → `geography(linestring)`|Creates a line between `a` and `b` -`geo_distance(a geography(point),b geography (point), unit string)` → `double`|Distance in the WGS84 ellipsoid between points `a` and `b` expressed in `unit` -`geo_buffer(p geography(point), r double, unit string)` → `geography(polygon)`|120-sided polygon around point `p`, which is fully enclosed by circle with center in same point and radius `r`, where radius unit is given in `unit`. When radius is 0, a single point is returned (the input parameter) instead of a 120-sided polygon -`geo_auto_vertex_order(arg geography)` → `geography`|Inverts the vertex order for all polygons if they are specified in an interior-right winding order assuming flat earth to topology [^4] -`geo_invert_vertex_order(arg geography)` → `geography`|Inverts the vertex order of all polygons +`tableau.geo_make_point(latitude double, longitude double)` → `tableau.tabgeography(point)`|Creates a point with coordinates `latitude` and `longitude` +`tableau.geo_make_line(a tableau.tabgeography(point), b tableau.tabgeography(point))` → `tableau.tabgeography(linestring)`|Creates a line between `a` and `b` +`tableau.geo_distance(a tableau.tabgeography(point),b tableau.tabgeography (point), unit string)` → `double`|Distance in the WGS84 ellipsoid between points `a` and `b` expressed in `unit` +`tableau.geo_buffer(p tableau.tabgeography(point), r double, unit string)` → `tableau.tabgeography(polygon)`|120-sided polygon around point `p`, which is fully enclosed by circle with center in same point and radius `r`, where radius unit is given in `unit`. When radius is 0, a single point is returned (the input parameter) instead of a 120-sided polygon +`tableau.geo_auto_vertex_order(arg tableau.tabgeography)` → `tableau.tabgeography`|Inverts the vertex order for all polygons if they are specified in an interior-right winding order assuming flat earth to topology [^4] +`tableau.geo_invert_vertex_order(arg tableau.tabgeography)` → `tableau.tabgeography`|Inverts the vertex order of all polygons :::note -Explicit use of `geo_auto_vertex_order` is needed and recommended +Explicit use of `tableau.geo_auto_vertex_order` is needed and recommended only when processing extracts generated by Hyper API version -v0.0.12514 or earlier. `geo_auto_vertex_order` is implicitly used -when parsing `GEOGRAPHY` values from WKT format. +v0.0.12514 or earlier. `tableau.geo_auto_vertex_order` is implicitly used +when parsing `TABLEAU.TABGEOGRAPHY` values from WKT format. ::: ### Examples -To pass a `geography` constant as an argument, it needs to be cast -from a string which contains a `geography` object formatted in the -Well Known Text (WKT) format defined by the Open GIS Consortium, +To pass a `tableau.tabgeography` constant as an argument, it needs to be cast +from a string which contains a `tableau.tabgeography` object formatted in the +Well-known text (WKT) format defined by the Open GIS Consortium, Inc, in the [OpenGIS Simple Features Specification For SQL](https://www.opengeospatial.org/standards/sfa). More examples of -handling `geography` objects using the Hyper API can be found +handling `tableau.tabgeography` objects using the Hyper API can be found [here](/docs/guides/hyper_file/geodata). -Return values of type `geography` are also shown in WKT format. +Return values of type `tableau.tabgeography` are also shown in WKT format. ``` -SELECT geo_make_point(20, 30); -Result: point(30.0000003 20.0) -(Note that the latitude and longitude are flipped in the result, because it is shown in the WKT format as point(longitude latitude).) +SELECT tableau.geo_make_point(20, 30); +Result: POINT(30.0000000 20.0000000) +(Note that the latitude and longitude are flipped in the result, because it is shown in the WKT format as point(longitude latitude)) -SELECT geo_make_line('point(14 42)'::geography,'point(18 43)'::geography); -Result: linestring(14.0000003 42.0000002, 18.0000003 43.0000001) +SELECT tableau.geo_make_line('point(14 42)'::tableau.tabgeography,'point(18 43)'::tableau.tabgeography); +Result: LINESTRING(14.0000000 42.0000000, 18.0000000 43.0000000) -SELECT geo_distance('point(0 0)'::geography, 'point(0 1)'::geography, 'kilometers'); -Result: 110.574372592802 +SELECT tableau.geo_distance('point(0 0)'::tableau.tabgeography, 'point(0 1)'::tableau.tabgeography, 'kilometers'); +Result: 110.574391628025 -SELECT geo_buffer('point(90 45)'::geography, 1989.0, 'meter'); -Result: polygon((90.0000002 45.0178973, 89.9986795 45.0178727, ..., 90.0013209 45.0178727, 90.0000002 45.0178973)) +SELECT tableau.geo_buffer('point(90 45)'::tableau.tabgeography, 1989.0, 'meter'); +Result: POLYGON((90.0000000 45.0178977, 89.9986793 45.0178731, ..., 90.0013206 45.0178731, 90.0000000 45.0178977)) -SELECT geo_invert_vertex_order('geometrycollection(polygon((0 0, 2 0, 0 4, 0 0)), polygon((0 0, 0 2, 4 0, 0 0)), point(0 2))'::geography); -Result: geometry collection(polygon((0.0 0.0,0.0 4.0,2.0000003 0.0,0.0 0.0)), polygon((0.0 0.0,4.0 0.0,0.0 2.0000003,0.0 0.0)), point(0.0 2.0000003)) +SELECT tableau.geo_invert_vertex_order('geometrycollection(polygon((0 0, 2 0, 0 4, 0 0)), polygon((0 0, 0 2, 4 0, 0 0)), point(0 2))'::tableau.tabgeography); +Result: GEOMETRYCOLLECTION(POINT(0.0000000 2.0000000), POLYGON((0.0000000 0.0000000, ..., 0.0625000 0.0000000, 0.0000000 0.0000000))) -SELECT geo_auto_vertex_order('geometrycollection(polygon((0 0, 2 0, 0 4, 0 0)), polygon((0 0, 0 2, 4 0, 0 0)), point(0 2))'::geography); -Result: geometrycollection(polygon((0.0 0.0,2.0000003 0.0,0.0 4.0,0.0 0.0)), polygon((0.0 0.0,4.0 0.0,0.0 2.0000003,0.0 0.0)),point(0.0 2.0000003)) +SELECT tableau.geo_auto_vertex_order('geometrycollection(polygon((0 0, 2 0, 0 4, 0 0)), polygon((0 0, 0 2, 4 0, 0 0)), point(0 2))'::tableau.tabgeography); +Result: GEOMETRYCOLLECTION(POINT(0.0000000 2.0000000), POLYGON((0.0000000 0.0000000, ..., 0.0000000 0.0625000, 0.0000000 0.0000000))) ``` ## Supported distance units The supported units of length are: -Unit name in American spelling| Other supported spellings|Description +Unit name in American spelling|Other supported spellings|Description ---|---|--- meter|metre, m, meters, metres|Base unit of length in International System of Units (SI) kilometer|kilometre, km, kilometers, kilometres|Equal to 1000 meters diff --git a/website/src/config.ts b/website/src/config.ts index e64f958..8a3f1c0 100644 --- a/website/src/config.ts +++ b/website/src/config.ts @@ -1,4 +1,4 @@ -const version_long = '0.0.21200.re11c8cb9'; +const version_long = '0.0.21408.rf5a406c0'; const version_short = version_long.substr(0, version_long.lastIndexOf('.')); const downloadBaseUrl = 'https://downloads.tableau.com/tssoftware/';