diff --git a/docs/dev/ASCRead.md b/docs/dev/ASCRead.md new file mode 100644 index 0000000000..539c7ce9d9 --- /dev/null +++ b/docs/dev/ASCRead.md @@ -0,0 +1,213 @@ +--- +layout: docs +title: ASCRead +category: h2drivers +is_function: true +description: ASC → Table +prev_section: h2drivers +next_section: CSVRead +permalink: /docs/dev/ASCRead/ +--- + +### Signatures + +{% highlight mysql %} +ASCRead(VARCHAR path); +ASCRead(VARCHAR path, BOOLEAN deleteTable); + +ASCRead(VARCHAR path, VARCHAR myTable); +ASCRead(VARCHAR path, VARCHAR myTable, BOOLEAN deleteTable); + +ASCRead(VARCHAR path, INTEGER type); +ASCRead(VARCHAR path, INTEGER type, BOOLEAN deleteTable); + +ASCRead(VARCHAR path, VARCHAR myTable, INTEGER type); +ASCRead(VARCHAR path, VARCHAR myTable, INTEGER type, BOOLEAN deleteTable); + +ASCRead(VARCHAR path, VARCHAR myTable, GEOMETRY geomFilter, + INTEGER downScaleInt, BOOLEAN asPolygons); +ASCRead(VARCHAR path, VARCHAR myTable, GEOMETRY geomFilter, + INTEGER downScaleInt, BOOLEAN asPolygons, BOOLEAN deleteTable); +{% endhighlight %} + +### Description + +Import Esri ASCII Raster file as `POINT` or `POLYGON` geometries. + +Pixels are converted into `PointZ` (or `PolygonZ`) geometry with Z as the pixel value (stored as `DOUBLE`). + +Where: + +- `path` : adress of the `.asc` file. This file may be zipped in a `.gz` file *(in this case, the `ASCRead` driver will unzip on the fly the `.gz` file)*, +- `myTable` : name of the output table, +- `type` : indicates whether the `z` data type will be casted to INTEGER (`1`) or left as DOUBLE (`2` - default value), +- `geomFilter` : extract only pixels that intersects the provided geometry envelope (`null` or empty argument to disable filter), +- `downScaleInt` : a coefficient used for exporting less cells (`1` all cells, `2` for size / 2, ...), +- `asPolygons` : if `true`, pixels are converted into polygons (default value = `false` return points), +- `deleteTable` : if `true` and table `tableName` already exists in the database, then table `tableName` will be removed / replaced by the new one. Else (no `deleteTable` parameter or `deleteTable` equal to `false`), throw an exception if the `tableName` already exist. + +### Examples + +We assume that we have the following `.asc` file, named `dem` and placed here: `/home/user/`. + +```java +ncols 4 +nrows 4 +xllcorner 10 +yllcorner 10 +cellsize 5.0 +NODATA_value -9999 + 28 27 26 25 + 27 25 24 23 + 26 23 20 19 + 25 20 18 17 +``` + + +##### 1. Using the `path` + +{% highlight mysql %} +CALL ASCREAD('/home/user/dem.asc'); +{% endhighlight %} + +Returns the table `dem`, with the following values: + +| PK | THE_GEOM | Z | +|:-----:|:--------:|:---:| +| 1 | POINT Z (12.5 27.5 28) | 28.0 | +| 2 | POINT Z (17.5 27.5 27) | 27.0 | +| 3 | POINT Z (22.5 27.5 26) | 26.0 | +| 4 | POINT Z (27.5 27.5 25) | 25.0 | +| 5 | POINT Z (12.5 22.5 27) | 27.0 | +| 6 | POINT Z (17.5 22.5 25) | 25.0 | +| 7 | POINT Z (22.5 22.5 24) | 24.0 | +| 8 | POINT Z (27.5 22.5 23) | 23.0 | +| 9 | POINT Z (12.5 17.5 26) | 26.0 | +| 10 | POINT Z (17.5 17.5 23) | 23.0 | +| 11 | POINT Z (22.5 17.5 20) | 20.0 | +| 12 | POINT Z (27.5 17.5 19) | 19.0 | +| 13 | POINT Z (12.5 12.5 25) | 25.0 | +| 14 | POINT Z (17.5 12.5 20) | 20.0 | +| 15 | POINT Z (22.5 12.5 18) | 18.0 | +| 16 | POINT Z (27.5 12.5 17) | 17.0 | + +**Remark**: If the `dem.asc` has been zipped into a `.gz` file, execute the following instruction: + +{% highlight mysql %} +CALL ASCREAD('/home/user/dem.asc.gz'); +{% endhighlight %} + +In this case, since the `myTable` parameter has not been specified, the resuling table will be named `DEM_ASC`. + +##### 2. Using `myTable` + +{% highlight mysql %} +CALL ASCREAD('/home/user/dem.asc', 'myDEMTable'); +{% endhighlight %} + +Returns the table `myDEMTable` (same as `dem` table) + +| PK | THE_GEOM | Z | +|:-----:|:--------:|:---:| +| 1 | POINT Z (12.5 27.5 28) | 28.0 | +| 2 | POINT Z (17.5 27.5 27) | 27.0 | +| ... | ... | ... | + + +##### 3. Using `type` + +Here we want to convert Z value into INTEGER +{% highlight mysql %} +CALL ASCREAD('/home/user/dem.asc', 1); +{% endhighlight %} + +Returns the table `myDEMTable` + +| PK | THE_GEOM | Z | +|:-----:|:--------:|:---:| +| 1 | POINT Z (12.5 27.5 28) | 28 | +| 2 | POINT Z (17.5 27.5 27) | 27 | +| ... | ... | ... | + + +##### 4. Using `geomFilter` +Here, we want to keep only `POINT`s that intersect this geometry: `POLYGON((15 15, 15 25, 25 25, 25 15, 15 15))` + +{% highlight mysql %} +CALL ASCREAD( + '/home/user/dem.asc', + 'myDEMTable', + ST_GeomFromText('POLYGON((15 15, 15 25, 25 25, 25 15, 15 15))'), + 1, false); +{% endhighlight %} + +Returns the table `myDEMTable`, with the following values: + +| PK | THE_GEOM | Z | +|:----:|:----------------------:|:---:| +| 1 | POINT Z (17.5 22.5 25) | 25.0 | +| 2 | POINT Z (22.5 22.5 24) | 24.0 | +| 3 | POINT Z (27.5 22.5 23) | 23.0 | +| 4 | POINT Z (17.5 17.5 23) | 23.0 | +| 5 | POINT Z (22.5 17.5 20) | 20.0 | +| 6 | POINT Z (27.5 17.5 19) | 19.0 | +| 7 | POINT Z (17.5 12.5 20) | 20.0 | +| 8 | POINT Z (22.5 12.5 18) | 18.0 | +| 9 | POINT Z (27.5 12.5 17) | 17.0 | + + +##### 5. Using `downScaleInt` + +Here we want to divide the matrix size by 2 + +{% highlight mysql %} +CALL ASCREAD('/home/user/dem.asc', 'myDEMTable', null, 2, false); +{% endhighlight %} + +Returns the table `myDEMTable`, with the following values: + +| PK | THE_GEOM | Z | +|:----:|:----------------------:|:---:| +| 1 | POINT Z (12.5 27.5 28) | 28.0 | +| 2 | POINT Z (22.5 27.5 26) | 26.0 | +| 3 | POINT Z (12.5 17.5 26) | 26.0 | +| 4 | POINT Z (22.5 17.5 20) | 20.0 | + + +##### 6. Using `asPolygons` + +Here we want to have a resulting `POLYGON` layer. + +{% highlight mysql %} +CALL ASCREAD('/home/user/dem.asc', 'myDEMTable', null, 1, true); +{% endhighlight %} + +Returns the table `myDEMTable`, with the following values: + + + +| PK | THE_GEOM | Z | +|:----:|:--------------------------------------------------------------:|:---:| +| 1 | POLYGON Z ((10 30 28, 10 25 28, 15 25 28, 15 30 28, 10 30 28)) | 28.0 | +| 2 | POLYGON Z ((15 30 27, 15 25 27, 20 25 27, 20 30 27, 15 30 27)) | 27.0 | +| 3 | POLYGON Z ((20 30 26, 20 25 26, 25 25 26, 25 30 26, 20 30 26)) | 26.0 | +| 4 | POLYGON Z ((25 30 25, 25 25 25, 30 25 25, 30 30 25, 25 30 25)) | 25.0 | +| 5 | POLYGON Z ((10 25 27, 10 20 27, 15 20 27, 15 25 27, 10 25 27)) | 27.0 | +| 6 | POLYGON Z ((15 25 25, 15 20 25, 20 20 25, 20 25 25, 15 25 25)) | 25.0 | +| 7 | POLYGON Z ((20 25 24, 20 20 24, 25 20 24, 25 25 24, 20 25 24)) | 24.0 | +| 8 | POLYGON Z ((25 25 23, 25 20 23, 30 20 23, 30 25 23, 25 25 23)) | 23.0 | +| 9 | POLYGON Z ((10 20 26, 10 15 26, 15 15 26, 15 20 26, 10 20 26)) | 26.0 | +| 10 | POLYGON Z ((15 20 23, 15 15 23, 20 15 23, 20 20 23, 15 20 23)) | 23.0 | +| 11 | POLYGON Z ((20 20 20, 20 15 20, 25 15 20, 25 20 20, 20 20 20)) | 20.0 | +| 12 | POLYGON Z ((25 20 19, 25 15 19, 30 15 19, 30 20 19, 25 20 19)) | 19.0 | +| 13 | POLYGON Z ((10 15 25, 10 10 25, 15 10 25, 15 15 25, 10 15 25)) | 25.0 | +| 14 | POLYGON Z ((15 15 20, 15 10 20, 20 10 20, 20 15 20, 15 15 20)) | 20.0 | +| 15 | POLYGON Z ((20 15 18, 20 10 18, 25 10 18, 25 15 18, 20 15 18)) | 18.0 | +| 16 | POLYGON Z ((25 15 17, 25 10 17, 30 10 17, 30 15 17, 25 15 17)) | 17.0 | + + +##### See also + +* [`CSVRead`](../CSVRead) +* Source code diff --git a/docs/dev/ASCRead_1.png b/docs/dev/ASCRead_1.png new file mode 100644 index 0000000000..57f611dd55 Binary files /dev/null and b/docs/dev/ASCRead_1.png differ diff --git a/docs/dev/CSVRead.md b/docs/dev/CSVRead.md index 2cc1abd87e..da4daa64c9 100644 --- a/docs/dev/CSVRead.md +++ b/docs/dev/CSVRead.md @@ -4,7 +4,7 @@ title: CSVRead category: h2drivers is_function: true description: CSV → Table -prev_section: h2drivers +prev_section: ASCRead next_section: CSVWrite permalink: /docs/dev/CSVRead/ --- diff --git a/docs/dev/CSVWrite.md b/docs/dev/CSVWrite.md index 74476da22a..343fe5da1c 100644 --- a/docs/dev/CSVWrite.md +++ b/docs/dev/CSVWrite.md @@ -26,42 +26,49 @@ CSVWrite(VARCHAR path, VARCHAR sqlSelectTable, target="_blank">documentation on the H2 website.

-Writes a CSV file from the SQL select statement `sqlSelectTable` to -the CSV file specified by `path`. +Writes a CSV file from the SQL select statement `sqlSelectTable` to the CSV file specified by `path`. {% include stringDecode.html %} ### Examples +In the following examples, we are using a table named `AREA` and defined as follow: + {% highlight mysql %} --- Create an example table to use with CSVWrite: CREATE TABLE AREA(THE_GEOM VARCHAR(100), ID INT PRIMARY KEY); INSERT INTO AREA VALUES ('POLYGON((-10 109, 90 9, -10 9, -10 109))', 1), ('POLYGON((90 109, 190 9, 90 9, 90 109))', 2); --- Write it to a CSV file: +{% endhighlight %} + +Write it to a CSV file: +{% highlight mysql %} CALL CSVWrite('/home/user/area.csv', 'SELECT * FROM AREA'); + -- Read it back: SELECT * FROM CSVRead('/home/user/area.csv'); -- Answer: --- | THE_GEOM | ID | --- | ---------------------------------------- | ------ | --- | POLYGON((-10 109, 90 9, -10 9, -10 109)) | 1 | --- | POLYGON((90 109, 190 9, 90 9, 90 109)) | 2 | +-- | THE_GEOM | ID | +-- | ---------------------------------------- | -- | +-- | POLYGON((-10 109, 90 9, -10 9, -10 109)) | 1 | +-- | POLYGON((90 109, 190 9, 90 9, 90 109)) | 2 | +{% endhighlight %} --- Try writing it with a specific charset and field separator: +Try writing it with a specific charset and field separator: + +{% highlight mysql %} CALL CSVWRITE('/home/user/area.csv', - 'SELECT * FROM AREA', 'charset=UTF-8 - fieldSeparator=;'); + 'SELECT * FROM AREA', + 'charset=UTF-8 fieldSeparator=;'); -- Read it back: SELECT * FROM CSVRead('/home/user/area.csv', NULL, 'charset=UTF-8 fieldSeparator=;'); -- Answer: --- | THE_GEOM | ID | --- | ---------------------------------------- | ------ | --- | POLYGON((-10 109, 90 9, -10 9, -10 109)) | 1 | --- | POLYGON((90 109, 190 9, 90 9, 90 109)) | 2 | +-- | THE_GEOM | ID | +-- | ---------------------------------------- | -- | +-- | POLYGON((-10 109, 90 9, -10 9, -10 109)) | 1 | +-- | POLYGON((90 109, 190 9, 90 9, 90 109)) | 2 | {% endhighlight %} ##### See also diff --git a/docs/dev/DBFRead.md b/docs/dev/DBFRead.md index 8936b72190..75eea1718b 100644 --- a/docs/dev/DBFRead.md +++ b/docs/dev/DBFRead.md @@ -13,18 +13,28 @@ permalink: /docs/dev/DBFRead/ {% highlight mysql %} DBFRead(VARCHAR path); +DBFRead(VARCHAR path, BOOLEAN deleteTable); + DBFRead(VARCHAR path, VARCHAR tableName); +DBFRead(VARCHAR path, VARCHAR tableName, BOOLEAN deleteTable); + DBFRead(VARCHAR path, VARCHAR tableName, VARCHAR fileEncoding); +DBFRead(VARCHAR path, VARCHAR tableName, VARCHAR fileEncoding, + BOOLEAN deleteTable); {% endhighlight %} ### Description -Reads the file specified by `path` as a [dBase][wiki] file and -copies its contents into a new table `tableName` in the database. -Define `fileEncoding` to force encoding (useful when the header is -missing encoding information). +Reads the file specified by `path` as a [dBase][wiki] file and copies its contents into a new table `tableName` in the database. + +A new column named `PK`, storing a primary key (`INT` value), is added. If the input `.dbf` has already a `PK` column then the added column is named `PK2` *(and so on)*. -If the `tablename` parameter is not specified, then the resulting table has the same name as the dBase file. +Define `fileEncoding` to force encoding (useful when the header is missing encoding information) (default value is `ISO-8859-1`). + +If: + +- the `tablename` parameter is not specified, then the resulting table has the same name as the dBase file. +- the `deleteTable` parameter is `true` and table `tableName` already exists in the database, then table `tableName` will be removed / replaced by the new one. Else (no `deleteTable` parameter or `deleteTable` equal to `false`), an error indicating that the table `tableName` already exists will be throwned.
Warning on the input file name
@@ -33,33 +43,93 @@ If the `tablename` parameter is not specified, then the resulting table has the ### Examples +In following example, we have a DBF file, which is stored here : `/home/user/city.dbf`. This file is structured as follow. + {% highlight mysql %} --- Basic syntax: -CALL DBFRead('/home/user/file.dbf', 'tableName'); - --- In the next two examples, we show what happens when we attempt to --- read a DBF file with the wrong encoding, and how to fix it. Here --- UTF-8 doesn't understand accented characters, so "Sévérac" is --- displayed as "S". -CALL DBFRead('/home/user/COMMUNE.DBF', 'commune44utf', 'utf-8'); -SELECT * FROM commune44utf LIMIT 2; +NAME ID +Vannes 56260 +Theix 56251 +Bréhan 56206 +{% endhighlight %} + +#### 1. Case with `path` + +{% highlight mysql %} +CALL DBFRead('/home/user/city.dbf'); +{% endhighlight %} + +Returns the following table `CITY`. A column `PK` has been added. + +| PK | NAME | ID | +|:--:|:---------:|:-----:| +| 1 | Vannes | 56260 | +| 2 | Theix | 56251 | +| 3 | Bréhan | 56206 | + +#### 2. Case with `tableName` + +{% highlight mysql %} +CALL DBFRead('/home/user/city.dbf', 'MYCITY'); +{% endhighlight %} + +Returns the table `MYCITY` + +#### 3. Case with `fileEncoding` + +In the next two examples, we show what happens when we attempt to read a DBF file with the wrong encoding, and how to fix it. +Here UTF-8 doesn't understand accented characters, so "`Bréhan`" is displayed as "`Br`". + +{% highlight mysql %} +CALL DBFRead('/home/user/city.dbf', 'CITY', 'utf-8'); + -- Answer: --- | NOM | CODE_INSEE | DEPART | REGION | --- |--------|------------|------------------|------------------| --- | Puceul | 44138 | LOIRE-ATLANTIQUE | PAYS DE LA LOIRE | --- | S | 44196 | LOIRE-ATLANTIQUE | PAYS DE LA LOIRE | - --- To fix this problem, we specify the right encoding: -CALL DBFRead('/home/user/COMMUNE.DBF', 'commune44iso', - 'iso-8859-1'); -SELECT * FROM commune44iso LIMIT 2; +-- | PK | NAME | ID | +-- |----|--------|-------| +-- | 1 | Vannes | 56260 | +-- | 2 | Theix | 56251 | +-- | 3 | Br | 56206 | +{% endhighlight %} + +To fix this problem, we specify the right encoding (`iso-8859-1`): + +{% highlight mysql %} +CALL DBFRead('/home/user/city.dbf', 'CITY', 'iso-8859-1'); + -- Answer: --- | NOM | CODE_INSEE | DEPART | REGION | --- |---------|------------|------------------|------------------| --- | Puceul | 44138 | LOIRE-ATLANTIQUE | PAYS DE LA LOIRE | --- | Sévérac | 44196 | LOIRE-ATLANTIQUE | PAYS DE LA LOIRE | +-- | PK | NAME | ID | +-- |----|--------|-------| +-- | 1 | Vannes | 56260 | +-- | 2 | Theix | 56251 | +-- | 3 | Bréhan | 56206 | +{% endhighlight %} + + +#### 4. Case with `deleteTable` + +Load the `city.dbf` file +{% highlight mysql %} +CALL DBFRead('/home/user/city.dbf'); +{% endhighlight %} + +→ the table `CITY` is created. + +Now, load once again, using `deleteTable` = `true` + +{% highlight mysql %} +CALL DBFRead('/home/user/city.dbf', true); {% endhighlight %} +→ the already existing `CITY` table is removed / replaced. + +Now, load once again, using `deleteTable` = `false` + +{% highlight mysql %} +CALL DBFRead('/home/user/city.dbf', false); +{% endhighlight %} + +→ Error message: `The table "CITY" already exists`. + + ##### See also * [`DBFWrite`](../DBFWrite) diff --git a/docs/dev/DBFWrite.md b/docs/dev/DBFWrite.md index b51cf1be64..6ae9b9de05 100644 --- a/docs/dev/DBFWrite.md +++ b/docs/dev/DBFWrite.md @@ -13,36 +13,98 @@ permalink: /docs/dev/DBFWrite/ {% highlight mysql %} DBFWrite(VARCHAR path, VARCHAR tableName); +DBFWrite(VARCHAR path, VARCHAR tableName, BOOLEAN deleteTable); DBFWrite(VARCHAR path, VARCHAR tableName, VARCHAR fileEncoding); +DBFWrite(VARCHAR path, VARCHAR tableName, VARCHAR fileEncoding, + BOOLEAN deleteTable); {% endhighlight %} ### Description -Writes the contents of table `tableName` to a [dBase][wiki] file -located at `path`. -The default value of `fileEncoding` is `ISO-8859-1`. +Writes the contents of table `tableName` to a [dBase][wiki] file located at `path`. + +`tableName` can be either: + +* the name of an existing table, +* the result of a query (`SELECT` instruction which has to be written between simple quote and parenthesis `'( )'`). **Warning**: when using text value in the `WHERE` condition, you have to double the simple quote (different from double quote ""): `... WHERE TextColumn = ''myText''`. + +Define `fileEncoding` to force encoding (useful when the header is missing encoding information) (default value is `ISO-8859-1`). + +If the `deleteTable` parameter is `true` and `path` file already exists, then `path` file will be removed / replaced by the new one. Else (no `deleteTable` parameter or `deleteTable` equal to `false`), an error indicating that the `path` file already exists will be throwned. ### Examples + +In following example, we have a table called `CITY` and structured as follow. {% highlight mysql %} --- Basic syntax: -CALL DBFWrite('/home/user/file.dbf', 'tableName'); +CREATE TABLE CITY (NAME VARCHAR, ID INT); +INSERT INTO CITY VALUES ('Vannes', 56260), + ('Theix', 56251), + ('Saint-Avé', 56206); +{% endhighlight %} --- Write a DBF file with UTF-8 encoding that was read with --- ISO-8859-1 encoding: -CALL DBFWrite('/home/user/COMMUNE44.DBF', 'COMMUNE44iso-8859-1', - 'utf-8'); +#### 1. Case with `tableName` + +{% highlight mysql %} +-- Write the .dbf file ... +CALL DBFWrite('/home/user/city.dbf', 'CITY'); + +-- ... and read it back +CALL DBFRead('/home/user/city.dbf', 'CITY2'); +SELECT * FROM CITY2; --- Read it back, using the encoding present in the header: -CALL DBFRead('/home/user/COMMUNE44.DBF', 'commune44'); -SELECT * FROM commune44 LIMIT 2; -- Answer: --- | NOM | CODE_INSEE | DEPART | REGION | --- |---------|------------|------------------|------------------| --- | Puceul | 44138 | LOIRE-ATLANTIQUE | PAYS DE LA LOIRE | --- | Sévérac | 44196 | LOIRE-ATLANTIQUE | PAYS DE LA LOIRE | +-- +--| PK | NAME | ID | +--|----|-----------|-------| +--| 1 | Vannes | 56260 | +--| 2 | Theix | 56251 | +--| 3 | Saint-Avé | 56206 | {% endhighlight %} +#### 2. Case where `tableName` is the result of a selection + +{% highlight mysql %} +CALL DBFWrite('/home/user/city.dbf', + '(SELECT * FROM CITY WHERE NAME=''Vannes'')'); + +-- ... and read it back +CALL DBFRead('/home/user/city.dbf', 'CITY2'); +SELECT * FROM CITY2; + +-- Answer: +-- +--| PK | NAME | ID | +--|----|-----------|-------| +--| 1 | Vannes | 56260 | +{% endhighlight %} + + +#### 3. Case with `fileEncoding` + +{% highlight mysql %} +CALL DBFWrite('/home/user/city.dbf', 'CITY', 'utf-8'); +{% endhighlight %} + +#### 4. Case with `deleteTable` +We condisder that the `city.dbf` already exists here `/home/user/` +{% highlight mysql %} +CALL DBFWrite('/home/user/city.dbf', 'CITY', true); +-- or +CALL DBFWrite('/home/user/city.dbf', 'CITY', 'utf-8', true); +{% endhighlight %} +Since we have `deleteTable` = `true`, the file `city.dbf` is overwritten. + +Now, execute with `deleteTable` = `false` +{% highlight mysql %} +CALL DBFWrite('/home/user/city.dbf', 'CITY', false); +-- or +CALL DBFWrite('/home/user/city.dbf', 'CITY', 'utf-8', false); +{% endhighlight %} + +An error message is throwned: `The dbf file already exists` + + ##### See also * [`DBFRead`](../DBFRead) diff --git a/docs/dev/FILE_TABLE.md b/docs/dev/FILE_TABLE.md index 506c897562..38a4d607c5 100644 --- a/docs/dev/FILE_TABLE.md +++ b/docs/dev/FILE_TABLE.md @@ -33,36 +33,41 @@ Currently supported: ### Examples + +#### Basic syntax {% highlight mysql %} --- Basic syntax: CALL FILE_TABLE('/home/user/myshapefile.shp', 'tableName'); CALL FILE_TABLE('/home/user/dbase.dbf', 'tableName'); +{% endhighlight %} --- The next two examples show that which driver to use is detected --- automatically from the file extension: -CALL FILE_TABLE('/home/user/COMMUNE.DBF', 'commune'); -SELECT * FROM commune LIMIT 2; +#### Auto detect +The next two examples show that the driver to use is automatically detected from the file extension: + +{% highlight mysql %} +CALL FILE_TABLE('/home/user/CITY.DBF', 'citydbf'); +SELECT * FROM citydbf LIMIT 2; -- Answer: --- | NOM | CODE_INSEE | DEPART | REGION | --- |---------|------------|------------------|------------------| --- | Puceul | 44138 | LOIRE-ATLANTIQUE | PAYS DE LA LOIRE | --- | Sévérac | 44196 | LOIRE-ATLANTIQUE | PAYS DE LA LOIRE | +-- | NAME | CODE | +-- |---------|-------| +-- | Puceul | 44138 | +-- | Sévérac | 44196 | -CALL FILE_TABLE('/home/user/COMMUNE.SHP', 'commune44'); -SELECT * FROM commune44 LIMIT 2; +CALL FILE_TABLE('/home/user/CITY.SHP', 'cityshp'); +SELECT * FROM cityshp LIMIT 2; -- Answer: --- | the_geom | NOM | --- | ----------------------------------------- | ------- | --- | MULTIPOLYGON(((350075.2 6719771.8, | Puceul | --- | 350072.7 6719775.5, 350073 6719780.7, | | --- | 350075.2 6719771.8))) | | --- | MULTIPOLYGON(((317341.5 6727021, | Sévérac | --- | 317309.9 6727036.8, 317193.3 6727066.5, | | --- | 317341.5 6727021))) | | +-- | THE_GEOM | NAME | CODE | +-- | ---------------------------------------- | ------- | ----- | +-- | MULTIPOLYGON(((350075.2 6719771.8, | Puceul | 44138 | +-- | 350072.7 6719775.5, 350073 6719780.7, | | | +-- | 350075.2 6719771.8))) | | | +-- | MULTIPOLYGON(((317341.5 6727021, | Sévérac | 44196 | +-- | 317309.9 6727036.8, 317193.3 6727066.5, | | | +-- | 317341.5 6727021))) | | | {% endhighlight %} ##### See also +* [`SHPRead`](../SHPRead), [`DBFRead`](../DBFRead) * Source code [wikidbf]: http://en.wikipedia.org/wiki/DBase diff --git a/docs/dev/GPXRead.md b/docs/dev/GPXRead.md index c169ef3508..6a95584ad8 100644 --- a/docs/dev/GPXRead.md +++ b/docs/dev/GPXRead.md @@ -13,18 +13,23 @@ permalink: /docs/dev/GPXRead/ {% highlight mysql %} GPXRead(VARCHAR path); +GPXRead(VARCHAR path, BOOLEAN deleteTable); GPXRead(VARCHAR path, VARCHAR tableName); -GPXRead(VARCHAR path, VARCHAR tableName, BOOLEAN deleteTables); +GPXRead(VARCHAR path, VARCHAR tableName, + BOOLEAN deleteTable); +GPXRead(VARCHAR path, VARCHAR tableName, + VARCHAR fileEncoding); +GPXRead(VARCHAR path, VARCHAR tableName, + VARCHAR fileEncoding, BOOLEAN deleteTable); + + {% endhighlight %} ### Description -Reads a [GPX][wiki] file from `path` and creates several tables -prefixed by `tableName` representing the file's contents. If `deleteTables` is equal to `true`, existing tables (with the same prefix) are removed. - +Reads a [GPX][wiki] file from `path` and creates several tables prefixed by `tableName` representing the file's contents. -Tables are produced depending on the content of the GPX file, -and may include: +Tables are produced depending on the content of the GPX file, and may include: * `TABLENAME_WAYPOINT` * `TABLENAME_ROUTE` @@ -33,8 +38,12 @@ and may include: * `TABLENAME_TRACKPOINT` * `TABLENAME_TRACKSEGMENT` -By default, the `tableName` is the filename given in `path` without -the extension. +Define `fileEncoding` to force encoding (useful when the header is missing encoding information) (default value is `ISO-8859-1`). + +If: + +- the `tablename` parameter is not specified, then the resulting tables are prefixed with the same name as the GPX file. +- the `deleteTable` parameter is `true` and tables prefixed with `tableName` already exists in the database, then tables `tableName` will be removed / replaced by the new ones. Else (no `deleteTable` parameter or `deleteTable` equal to `false`), an error indicating that the tables prefixed with `tableName` already exists will be throwned.
Warning on the input file name
@@ -43,26 +52,109 @@ the extension. ### Examples +In the following example, we are using two `.gpx` files presented below *(and coming from this [webpage](https://www.rigacci.org/wiki/doku.php/tecnica/gps_cartografia_gis/gpx))* and stored in `/home/user/`: + +Track file : `road.gpx` + +{% highlight xml %} + + ACTIVE LOG + + + 66.468262 + + + + 40.032104 + + + + 40.512817 + + + + +{% endhighlight %} + +Waypoints file : `station.gpx` + +{% highlight xml %} + + 74.387085 + 020 + 020 + 020 + Flag + +{% endhighlight %} + +#### 1. Using `path` + +**a. With a `track` file** + +{% highlight mysql %} +CALL GPXRead('/home/user/road.gpx'); +{% endhighlight %} + +Returns the following tables: + +- ROAD_TRACK +- ROAD_TRACKPOINT +- ROAD_TRACKSEGMENT + +**b. With a `waypoints` file** + {% highlight mysql %} --- Takes the table name from the filename, producing --- * ROUTE_TRACK --- * ROUTE_TRACKPOINT --- * ROUTE_TRACKSEGMENT -CALL GPXRead('/home/user/route.gpx'); - --- Uses the given table name, producing --- * GPXDATA_TRACK --- * GPXDATA_TRACKPOINT --- * GPXDATA_TRACKSEGMENT -CALL GPXRead('/home/user/route.gpx', 'GPXDATA'); - --- Existing tables starting with 'GPXDATA' will be removed -CALL GPXRead('/home/user/route.gpx', 'GPXDATA', true); - --- Produces STATION_WAYPOINT. CALL GPXRead('/home/user/station.gpx'); {% endhighlight %} +Returns the following table: + +- STATION_WAYPOINT + +#### 2. Using `path` and `tableName` + +{% highlight mysql %} +CALL GPXRead('/home/user/road.gpx', 'GPXROAD'); +{% endhighlight %} + +Returns the following tables: + +- GPXROAD_TRACK +- GPXROAD_TRACKPOINT +- GPXROAD_TRACKSEGMENT + +##### 3. Case with `fileEncoding` + +{% highlight mysql %} +CALL GPXRead('/home/user/road.gpx', 'GPXROAD', 'utf-8'); +{% endhighlight %} + +##### 4. Case with `deleteTable` + +Load the `road.gpx` file +{% highlight mysql %} +CALL GPXRead('/home/user/road.gpx', 'GPXROAD'); +{% endhighlight %} + +→ the tables `GPXROAD_TRACK`, `GPXROAD_TRACKPOINT` and `GPXROAD_TRACKSEGMENT` are created. + +Now, load once again, using `deleteTable` = `true` + +{% highlight mysql %} +CALL GPXRead('/home/user/road.gpx', 'GPXROAD', true); +{% endhighlight %} + +→ the already existing `GPXROAD_` tables are removed / replaced. + +Now, load once again, using `deleteTable` = `false` + +{% highlight mysql %} +CALL GPXRead('/home/user/road.gpx', 'GPXROAD', false); +{% endhighlight %} + +→ Error message: `The table "GPXROAD_TRACK" already exists`. + ##### See also * Source code diff --git a/docs/dev/GeoJsonRead.md b/docs/dev/GeoJsonRead.md index 91fa109975..e7b3b16684 100644 --- a/docs/dev/GeoJsonRead.md +++ b/docs/dev/GeoJsonRead.md @@ -13,15 +13,28 @@ permalink: /docs/dev/GeoJsonRead/ {% highlight mysql %} GeoJsonRead(VARCHAR path); +GeoJsonRead(VARCHAR path, BOOLEAN deleteTable); + GeoJsonRead(VARCHAR path, VARCHAR tableName); +GeoJsonRead(VARCHAR path, VARCHAR tableName, BOOLEAN deleteTable); + +GeoJsonRead(VARCHAR path, VARCHAR tableName, + VARCHAR fileEncoding); +GeoJsonRead(VARCHAR path, VARCHAR tableName, + VARCHAR fileEncoding, BOOLEAN deleteTable); {% endhighlight %} ### Description -Reads a [GeoJSON][wiki] file from `path` and creates the -corresponding spatial table `tableName`. +Reads a [GeoJSON][wiki] file from `path` and creates the corresponding spatial table `tableName`. This `.geojson` file may be zipped in a `.gz` file *(in this case, the `GeoJsonRead` driver will unzip on the fly the `.gz` file)*. + +Define `fileEncoding` to force encoding (useful when the header is missing encoding information) (default value is `ISO-8859-1`). + +If: + +- the `tablename` parameter is not specified, then the resulting table has the same name as the GeoJSON file. +- the `deleteTable` parameter is `true` and table `tableName` already exists in the database, then table `tableName` will be removed / replaced by the new one. Else (no `deleteTable` parameter or `deleteTable` equal to `false`), an error indicating that the table `tableName` already exists will be throwned. -If the `tablename` parameter is not specified, then the resulting table has the same name as the GeoJSON file.
Warning on the input file name
@@ -30,18 +43,59 @@ If the `tablename` parameter is not specified, then the resulting table has the ### Examples +##### 1. Case with `path` + {% highlight mysql %} CALL GeoJsonRead('/home/user/data.geojson'); {% endhighlight %} → Here `data.geojson` will produce a table named `data`. +{% highlight mysql %} +CALL GeoJsonRead('/home/user/data.geojson.gz'); +{% endhighlight %} + +→ Here `data.geojson.gz` will produce a table named `data_geojson`. + +##### 2. Case with `tableName` + {% highlight mysql %} CALL GeoJsonRead('/home/user/data.geojson', 'NEW_DATA'); {% endhighlight %} → Here `data.geojson` will produce a table named `NEW_DATA`. +##### 3. Case with `fileEncoding` + +{% highlight mysql %} +CALL GeoJsonRead('/home/user/data.geojson', 'NEW_DATA', 'utf-8'); +{% endhighlight %} + +##### 4. Case with `deleteTable` + +Load the `data.geojson` file +{% highlight mysql %} +CALL GeoJsonRead('/home/user/data.geojson'); +{% endhighlight %} + +→ the table `data` is created. + +Now, load once again, using `deleteTable` = `true` + +{% highlight mysql %} +CALL GeoJsonRead('/home/user/data.geojson', true); +{% endhighlight %} + +→ the already existing `data` table is removed / replaced. + +Now, load once again, using `deleteTable` = `false` + +{% highlight mysql %} +CALL GeoJsonRead('/home/user/data.geojson', false); +{% endhighlight %} + +→ Error message: `The table "DATA" already exists`. + ##### See also * [`GeoJsonWrite`](../GeoJsonWrite), [`ST_AsGeoJson`](../ST_AsGeoJson), [`ST_GeomFromGeoJson`](../ST_GeomFromGeoJson) diff --git a/docs/dev/GeoJsonWrite.md b/docs/dev/GeoJsonWrite.md index 6c52b523fe..2c16c819df 100644 --- a/docs/dev/GeoJsonWrite.md +++ b/docs/dev/GeoJsonWrite.md @@ -13,42 +13,65 @@ permalink: /docs/dev/GeoJsonWrite/ {% highlight mysql %} GeoJsonWrite(VARCHAR path, VARCHAR tableName); -GeoJsonWrite(VARCHAR path, VARCHAR tableName, VARCHAR fileEncoding); +GeoJsonWrite(VARCHAR path, VARCHAR tableName, + BOOLEAN deleteTable); +GeoJsonWrite(VARCHAR path, VARCHAR tableName, + VARCHAR fileEncoding); +GeoJsonWrite(VARCHAR path, VARCHAR tableName, + VARCHAR fileEncoding, BOOLEAN deleteTable); {% endhighlight %} ### Description -Writes the contents of table `tableName` to a [GeoJSON][wiki] file located at -`path`. +Writes the contents of table `tableName` to a [GeoJSON][wiki] file located at `path`. `tableName` can be either: * the name of an existing table, -* the result of a query (`SELECT` instruction which has to be written between simple quote and parenthesis `'( )'`). +* the result of a query (`SELECT` instruction which has to be written between simple quote and parenthesis `'( )'`). **Warning**: when using text value in the `WHERE` condition, you have to double the simple quote (different from double quote ""): `... WHERE TextColumn = ''myText''`. + + +The `.geojson` file may be zipped in a `.gz` file *(in this case, the `GeoJsonWrite` driver will zip on the fly the `.geojson` file)*. + +Define `fileEncoding` to force encoding (useful when the header is missing encoding information) (default value is `ISO-8859-1`). + +If the `deleteTable` parameter is `true` and `path` file already exists, then `path` file will be removed / replaced by the new one. Else (no `deleteTable` parameter or `deleteTable` equal to `false`), an error indicating that the `path` file already exists will be throwned. -The default value of `fileEncoding` is `ISO-8859-1`. ### Examples +In the following example, we are working with a table named `TEST` and defined as follow. {% highlight mysql %} --- Write a spatial table to a GeoJSON file: -CREATE TABLE TEST(ID INT PRIMARY KEY, THE_GEOM POINT); +CREATE TABLE TEST(ID INT PRIMARY KEY, THE_GEOM GEOMETRY(POINT)); INSERT INTO TEST VALUES (1, 'POINT(0 1)'); INSERT INTO TEST VALUES (2, 'POINT(2 4)'); +{% endhighlight %} +#### 1. Case with `path` and `tableName` + +{% highlight mysql %} +-- Write a spatial table to a GeoJSON file: CALL GeoJsonWrite('/home/user/test.geojson', 'TEST'); -- Read it back: CALL GeoJsonRead('/home/user/test.geojson', 'TEST2'); SELECT * FROM TEST2; -- Answer: --- | THE_GEOM | ID | --- |-------------|----| --- | POINT(0 1) | 1 | --- | POINT(2 4) | 2 | +-- | ID | THE_GEOM | +-- |----|-------------| +-- | 1 | POINT(0 1) | +-- | 2 | POINT(2 4) | {% endhighlight %} -#### Case where `tablename` is the result of a selection +If you want to compress your resulting `.geojson` file into a `.gz` file, just execute + +{% highlight mysql %} +CALL GeoJsonWrite('/home/user/test.geojson.gz', 'TEST'); +{% endhighlight mysql %} + +As a result, you will obtain a `test.geojson.gz` file in which there is the `test.geojson` resulting file. + +#### 2. Case where `tableName` is the result of a selection {% highlight mysql %} CALL GeoJsonWrite('/home/user/test.geojson', @@ -58,11 +81,35 @@ CALL GeoJsonWrite('/home/user/test.geojson', CALL GeoJsonRead('/home/user/test.geojson', 'TEST2'); SELECT * FROM TEST2; -- Answer: --- | THE_GEOM | ID | --- |-------------|----| --- | POINT(0 1) | 1 | +-- | ID | THE_GEOM | +-- |----|-------------| +-- | 1 | POINT(0 1) | +{% endhighlight %} + +#### 3. Case with `fileEncoding` + +{% highlight mysql %} +CALL GeoJsonWrite('/home/user/test.geojson', 'TEST', 'utf-8'); +{% endhighlight %} + +#### 4. Case with `deleteTable` +We condisder that the `test.geojson` already exists here `/home/user/` +{% highlight mysql %} +CALL GeoJsonWrite('/home/gpetit/test.geojson', 'TEST', true); +-- or +CALL GeoJsonWrite('/home/user/test.geojson', 'TEST', 'utf-8', true); +{% endhighlight %} +Since we have `deleteTable` = `true`, the file `test.geojson` is overwritten. + +Now, execute with `deleteTable` = `false` +{% highlight mysql %} +CALL GeoJsonWrite('/home/gpetit/test.geojson', 'TEST', false); +-- or +CALL GeoJsonWrite('/home/user/test.geojson', 'TEST', 'utf-8', false); {% endhighlight %} +An error message is throwned: `The geojson file already exists` + ##### See also * [`GeoJsonRead`](../GeoJsonRead), [`ST_AsGeoJson`](../ST_AsGeoJson), [`ST_GeomFromGeoJson`](../ST_GeomFromGeoJson) diff --git a/docs/dev/JsonWrite.md b/docs/dev/JsonWrite.md index 5b1a617291..283ecbffe0 100644 --- a/docs/dev/JsonWrite.md +++ b/docs/dev/JsonWrite.md @@ -4,7 +4,7 @@ title: JsonWrite category: h2drivers is_function: true description: Table → JSON -prev_section: GeoJsonWrite +prev_section: jsonWrite next_section: KMLWrite permalink: /docs/dev/JsonWrite/ --- @@ -13,30 +13,96 @@ permalink: /docs/dev/JsonWrite/ {% highlight mysql %} JsonWrite(VARCHAR path, VARCHAR tableName); +JsonWrite(VARCHAR path, VARCHAR tableName, BOOLEAN deleteTable); +JsonWrite(VARCHAR path, VARCHAR tableName, VARCHAR fileEncoding); +JsonWrite(VARCHAR path, VARCHAR tableName, + VARCHAR fileEncoding, BOOLEAN deleteTable); {% endhighlight %} ### Description Writes table `tableName` to a [JSON][wiki] file located at `path`. +`tableName` can be either: + +* the name of an existing table, +* the result of a query (`SELECT` instruction which has to be written between simple quote and parenthesis `'( )'`). **Warning**: when using text value in the `WHERE` condition, you have to double the simple quote (different from double quote ""): `... WHERE TextColumn = ''myText''`. + +The `.json` file may be zipped in a `.gz` file *(in this case, the `JsonWrite` driver will zip on the fly the `.json` file)*. + +Define `fileEncoding` to force encoding (useful when the header is missing encoding information) (default value is `ISO-8859-1`). + +If the `deleteTable` parameter is `true` and `path` file already exists, then `path` file will be removed / replaced by the new one. Else (no `deleteTable` parameter or `deleteTable` equal to `false`), an error indicating that the `path` file already exists will be throwned. + ### Examples -Write a spatial table and export it into a JSON file. +In the following example, we are working with a table named `TEST` and defined as follow. +{% highlight mysql %} +CREATE TABLE TEST(ID INT, THE_GEOM GEOMETRY(POINT), NAME VARCHAR); +INSERT INTO TEST VALUES (1, 'POINT(0 1)', 'Paris'), + (2, 'POINT(2 4)', 'Orléans'); +{% endhighlight %} +#### 1. Case with `path` and `tableName` + +Export the spatial table into a JSON file: {% highlight mysql %} --- Initialize the spatial table -CREATE TABLE TEST(ID INT PRIMARY KEY, THE_GEOM POINT); -INSERT INTO TEST VALUES (1, 'POINT(0 1)'); --- Export CALL JsonWrite('/home/user/test.json', 'TEST'); -{% endhighlight mysql %} +{% endhighlight %} Open the `test.json` file. +{% highlight json %} +{"ID":1,"THE_GEOM":"POINT (0 1)","NAME":"Paris"} +{"ID":2,"THE_GEOM":"POINT (2 4)","NAME":"Orléans"} +{% endhighlight json %} + +If you want to compress your resulting `.json` file into a `.gz` file, just execute + +{% highlight mysql %} +CALL JsonWrite('/home/user/test.json.gz', 'TEST'); +{% endhighlight mysql %} + +As a result, you will obtain a `test.json.gz` file in which there is the `test.json` resulting file. + +#### 2. Case where `tableName` is the result of a selection +{% highlight mysql %} +CALL JsonWrite('/home/user/test.json', + '(SELECT * FROM TEST WHERE NAME=''Orléans'' )'); +{% endhighlight %} + +Open the `test.json` file. {% highlight json %} -{"ID":1,"THE_GEOM":"POINT (0 1)"} +{"ID":2,"THE_GEOM":"POINT (2 4)","NAME":"Orléans"} {% endhighlight json %} + +#### 3. Case with `fileEncoding` + +{% highlight mysql %} +CALL JsonWrite('/home/user/test.json', 'TEST', 'utf-8'); +{% endhighlight %} + +#### 4. Case with `deleteTable` +We condisder that the `test.json` already exists here `/home/user/` +{% highlight mysql %} +CALL JsonWrite('/home/gpetit/test.json', 'TEST', true); +-- or +CALL JsonWrite('/home/user/test.json', 'TEST', 'utf-8', true); +{% endhighlight %} +Since we have `deleteTable` = `true`, the file `test.json` is overwritten. + +Now, execute with `deleteTable` = `false` +{% highlight mysql %} +CALL JsonWrite('/home/gpetit/test.json', 'TEST', false); +-- or +CALL JsonWrite('/home/user/test.json', 'TEST', 'utf-8', false); +{% endhighlight %} + +An error message is throwned: `The json file already exists` + + + ##### See also * [`GeoJsonWrite`](../GeoJsonWrite), [`GeoJsonRead`](../GeoJsonRead), [`ST_AsGeoJson`](../ST_AsGeoJson), [`ST_GeomFromGeoJson`](../ST_GeomFromGeoJson) diff --git a/docs/dev/KMLWrite.md b/docs/dev/KMLWrite.md index fecdb7cbf3..a46b8bab5e 100644 --- a/docs/dev/KMLWrite.md +++ b/docs/dev/KMLWrite.md @@ -3,7 +3,7 @@ layout: docs title: KMLWrite category: h2drivers is_function: true -description: KML, KMZ → Table +description: Table → KML, KMZ prev_section: JsonWrite next_section: SHPRead permalink: /docs/dev/KMLWrite/ @@ -13,6 +13,10 @@ permalink: /docs/dev/KMLWrite/ {% highlight mysql %} KMLWrite(VARCHAR path, VARCHAR tableName); +KMLWrite(VARCHAR path, VARCHAR tableName, BOOLEAN deleteTable); +KMLWrite(VARCHAR path, VARCHAR tableName, VARCHAR fileEncoding); +KMLWrite(VARCHAR path, VARCHAR tableName, + VARCHAR fileEncoding, BOOLEAN deleteTable); {% endhighlight %} ### Description @@ -20,20 +24,75 @@ KMLWrite(VARCHAR path, VARCHAR tableName); Writes table `tableName` to a [KML][wiki] file located at `path`. A coordinate reference system must be set to save a KML file. +`tableName` can be either: + +* the name of an existing table, +* the result of a query (`SELECT` instruction which has to be written between simple quote and parenthesis `'( )'`). **Warning**: when using text value in the `WHERE` condition, you have to double the simple quote (different from double quote ""): `... WHERE TextColumn = ''myText''`. + +The `.kml` file may be zipped in a `.kmz` file *(in this case, the `KMLWrite` driver will zip on the fly the `.kml` file)*. + +Define `fileEncoding` to force encoding (useful when the header is missing encoding information) (default value is `ISO-8859-1`). + +If the `deleteTable` parameter is `true` and `path` file already exists, then `path` file will be removed / replaced by the new one. Else (no `deleteTable` parameter or `deleteTable` equal to `false`), an error indicating that the `path` file already exists will be throwned. + + + ### Examples +In the following example, we are working with a table named `TEST` and defined as follow. + {% highlight mysql %} --- Create an example table to write to a KML file: -CREATE TABLE TEST(ID INT PRIMARY KEY, THE_GEOM POINT); -INSERT INTO TEST - VALUES (1, ST_GeomFromText('POINT(2.19 47.58)', 4326)); +CREATE TABLE TEST(ID INT, THE_GEOM GEOMETRY (POINT)); +INSERT INTO TEST VALUES + (1, ST_GeomFromText('POINT(2.19 47.58)', 4326)), + (2, ST_GeomFromText('POINT(2.45 48.17)', 4326)), + (3, ST_GeomFromText('POINT(2.95 48.63)', 4326)); +{% endhighlight %} --- Write it: +#### 1. Case with `path` and `tableName` + +{% highlight mysql %} +-- Write it as a KML CALL KMLWrite('/home/user/test.kml', 'TEST'); +-- or as a KMZ +CALL KMLWrite('/home/user/test.kmz', 'TEST'); {% endhighlight %} +#### 2. Case where `tableName` is the result of a selection + +{% highlight mysql %} +CALL KMLWrite('/home/user/test.kml', + '(SELECT * FROM TEST WHERE ID<2 )'); +{% endhighlight %} + +#### 3. Case with `fileEncoding` + +{% highlight mysql %} +CALL KMLWrite('/home/user/test.kml', 'TEST', 'utf-8'); +{% endhighlight %} + +#### 4. Case with `deleteTable` +We condisder that the `test.kml` already exists here `/home/user/` +{% highlight mysql %} +CALL KMLWrite('/home/gpetit/test.kml', 'TEST', true); +-- or +CALL KMLWrite('/home/user/test.kml', 'TEST', 'utf-8', true); +{% endhighlight %} +Since we have `deleteTable` = `true`, the file `test.kml` is overwritten. + +Now, execute with `deleteTable` = `false` +{% highlight mysql %} +CALL KMLWrite('/home/gpetit/test.kml', 'TEST', false); +-- or +CALL KMLWrite('/home/user/test.kml', 'TEST', 'utf-8', false); +{% endhighlight %} + +An error message is throwned: `The kml file already exists` + + ##### See also +* [`ST_AsKML`](../ST_AsKML) * Source code [wiki]: http://en.wikipedia.org/wiki/Keyhole_Markup_Language diff --git a/docs/dev/OSMRead.md b/docs/dev/OSMRead.md index 16829c189e..6ee4abc27e 100644 --- a/docs/dev/OSMRead.md +++ b/docs/dev/OSMRead.md @@ -14,7 +14,12 @@ permalink: /docs/dev/OSMRead/ {% highlight mysql %} OSMRead(VARCHAR path); OSMRead(VARCHAR path, VARCHAR tableName); -OSMRead(VARCHAR path, VARCHAR tableName, BOOLEAN deleteTables); +OSMRead(VARCHAR path, VARCHAR tableName, + BOOLEAN deleteTables); +OSMRead(VARCHAR path, VARCHAR tableName, + VARCHAR fileEncoding); +OSMRead(VARCHAR path, VARCHAR tableName, + VARCHAR fileEncoding, BOOLEAN deleteTables); {% endhighlight %} ### Description @@ -35,38 +40,55 @@ Reads a [OSM][wiki] file from `path` and creates several tables prefixed by `tab * (10) table_prefix + _way_member : table that stores all ways that are referenced into a relation -> ID_RELATION BIGINT, ID_WAY BIGINT, ROLE VARCHAR, WAY_ORDER INT. * (11) table_prefix + _relation_member : table that stores all relations that are referenced into a relation -> ID_RELATION BIGINT, ID_SUB_RELATION BIGINT, ROLE VARCHAR, RELATION_ORDER INT. + By default, the `tableName` is the filename given in `path` without the extension. -The OSM driver supports the following zipped extension : osm.gz and osm.bz2.
Warning on the input file name

When a tablename is not specified, special caracters in the input file name are not allowed. The possible caracters are as follow: A to Z, _ and 0 to 9.

+The OSM driver supports the following zipped extension : `osm.gz` and `osm.bz2`. + +Define `fileEncoding` to force encoding (useful when the header is missing encoding information) (default value is `ISO-8859-1`). + ### Examples -Read OSM file: +#### 1. Using `path` {% highlight mysql %} - --- Takes the table name from the filename CALL OSMRead('/home/user/bretagne.osm'); +{% endhighlight %} + +#### 2. Using `path` and `tableName` --- Uses the given table name + +{% highlight mysql %} CALL OSMRead('/home/user/bretagne.osm', 'OSM_BRETAGNE'); +{% endhighlight %} --- Uses a zipped file +#### 3. Using a zipped file + +{% highlight mysql %} CALL OSMRead('/home/user/bretagne.osm.gz', 'OSM_BRETAGNE'); +{% endhighlight %} --- Uses another zipped file -CALL OSMRead('/home/user/bretagne.osm.bz2', 'OSM_BRETAGNE'); +#### 4. Using `fileEncoding` + +{% highlight mysql %} +CALL OSMRead('/home/user/bretagne.osm', 'OSM_BRETAGNE', 'utf-8'); +{% endhighlight %} --- Uses the given table name --- and remove existing tables prefixed with 'OSM_BRETAGNE' -CALL OSMRead('/home/user/bretagne.osm', 'OSM_BRETAGNE', true); +#### 5. Using `deleteTables` + +{% highlight mysql %} +CALL OSMRead('/home/user/bretagne.osm', 'OSM_BRETAGNE', true); {% endhighlight %} + +#### 6. Build OSM data + Based on the created tables, the user can build other OSM data. H2GIS extract buildings: @@ -92,7 +114,7 @@ ST_MAKEPOLYGON(ST_MAKELINE(THE_GEOM)) THE_GEOM FROM (SELECT (SELECT ST_ACCUM(THE ##### See also -* [`ST_OSMDownloader`](../ST_OSMDownloader) +* [`ST_OSMDownloader`](../ST_OSMDownloader), [`ST_OSMMapLink`](../ST_OSMMapLink) * Source code [wiki]: http://wiki.openstreetmap.org/wiki/OSM_XML diff --git a/docs/dev/SHPRead.md b/docs/dev/SHPRead.md index 85ef65bf5a..e815066244 100644 --- a/docs/dev/SHPRead.md +++ b/docs/dev/SHPRead.md @@ -13,18 +13,26 @@ permalink: /docs/dev/SHPRead/ {% highlight mysql %} SHPRead(VARCHAR path); +SHPRead(VARCHAR path, BOOLEAN deleteTable); SHPRead(VARCHAR path, VARCHAR tableName); +SHPRead(VARCHAR path, VARCHAR tableName, BOOLEAN deleteTable); SHPRead(VARCHAR path, VARCHAR tableName, VARCHAR fileEncoding); +SHPRead(VARCHAR path, VARCHAR tableName, + VARCHAR fileEncoding, BOOLEAN deleteTable); {% endhighlight %} ### Description -Reads the file specified by `path` as a [shapefile][wiki] and copies its -contents into a new table `tableName` in the database. -Define `fileEncoding` to force encoding (useful when the header is -missing encoding information). +Reads the file specified by `path` as a [shapefile][wiki] and copies its contents into a new table `tableName` in the database. -If the `tablename` parameter is not specified, then the resulting table has the same name as the shapefile. +A new column named `PK`, storing a primary key (`INT` value), is added. If the input `.shp` has already a `PK` column then the added column is named `PK2` *(and so on)*. + +Define `fileEncoding` to force encoding (useful when the header is missing encoding information) (default value is `ISO-8859-1`). + +If: + +- the `tableName` parameter is not specified, then the resulting table has the same name as the shapefile. +- the `deleteTable` parameter is `true` and table `tableName` already exists in the database, then table `tableName` will be removed / replaced by the new one. Else (no `deleteTable` parameter or `deleteTable` equal to `false`), an error indicating that the table `tableName` already exists will be throwned.
Warning on the input file name
@@ -33,41 +41,82 @@ If the `tablename` parameter is not specified, then the resulting table has the ### Examples +In following example, we have a SHP file, which is stored here : `/home/user/city.shp`. This file is structured as follow. + +| THE_GEOM | NAME | ID | +|:---------------------:|:------:|:-----:| +| MULTIPOLYGON(((...))) | Vannes | 56260 | +| MULTIPOLYGON(((...))) | Theix | 56251 | +| MULTIPOLYGON(((...))) | Bréhan | 56024 | + +#### 1. Case with `path` + +{% highlight mysql %} +CALL SHPRead('/home/user/city.shp'); +{% endhighlight %} + +The table `CITY` is created and a new `PK` column is added: + +| PK | THE_GEOM | NAME | ID | +|:--:|:---------------------:|:------:|:-----:| +| 1 | MULTIPOLYGON(((...))) | Vannes | 56260 | +| ... | ... | ... | ... | + +#### 2. Case with `path` and `tableName` + +{% highlight mysql %} +CALL SHPRead('/home/user/city.shp', 'MyCity'); +{% endhighlight %} + +The table `MYCITY` is created. + +#### 3. Case with `fileEncoding` + +In the next two examples, we show what happens when we attempt to read a SHP file with the wrong encoding, and how to fix it. +Here UTF-8 doesn't understand accented characters, so the city named `Bréhan` is displayed as `Br`. + {% highlight mysql %} --- Basic syntax: -CALL SHPRead('/home/user/file.shp', 'tableName'); - --- In the next two examples, we show what happens when we attempt to --- read a SHP file with the wrong encoding, and how to fix it. Here --- UTF-8 doesn't understand accented characters, so "Sévérac" is --- displayed as "S". -CALL SHPRead('/home/user/COMMUNE.SHP', 'commune44utf', - 'utf-8'); -SELECT * FROM commune44utf LIMIT 2; +CALL SHPRead('/home/user/city.shp', 'CITYutf', 'utf-8'); +SELECT * FROM CITYutf; -- Answer: --- | THE_GEOM | NOM | --- | ----------------------------------------- | ------- | --- | MULTIPOLYGON(((350075.2 6719771.8, | Puceul | --- | 350072.7 6719775.5, 350073 6719780.7, | | --- | 350075.2 6719771.8))) | | --- | MULTIPOLYGON(((317341.5 6727021, | S | --- | 317309.9 6727036.8, 317193.3 6727066.5, | | --- | 317341.5 6727021))) | | - --- To fix this problem, we specify the right encoding: -CALL SHPRead('/home/user/COMMUNE.SHP', 'commune44iso', - 'iso-8859-1'); -SELECT * FROM commune44iso LIMIT 2; +-- | PK | THE_GEOM | NAME | ID | +-- |----| --------------------- | ------ | ----- | +-- | 1 | MULTIPOLYGON(((...))) | Vannes | 56260 | +-- | 2 | MULTIPOLYGON(((...))) | Theix | 56251 | +-- | 3 | MULTIPOLYGON(((...))) | Br | 56024 | + +{% endhighlight %} +To fix this problem, we specify the right encoding (`iso-8859-1`): + +{% highlight mysql %} +CALL SHPRead('/home/user/city.shp', 'CITYiso', 'iso-8859-1'); +SELECT * FROM CITYiso; -- Answer: --- | THE_GEOM | NOM | --- | ----------------------------------------- | ------- | --- | MULTIPOLYGON(((350075.2 6719771.8, | Puceul | --- | 350072.7 6719775.5, 350073 6719780.7, | | --- | 350075.2 6719771.8))) | | --- | MULTIPOLYGON(((317341.5 6727021, | Sévérac | --- | 317309.9 6727036.8, 317193.3 6727066.5, | | --- | 317341.5 6727021))) | | +-- | PK | THE_GEOM | NAME | ID | +-- |----| --------------------- | ------ | ----- | +-- | 1 | MULTIPOLYGON(((...))) | Vannes | 56260 | +-- | 2 | MULTIPOLYGON(((...))) | Theix | 56251 | +-- | 3 | MULTIPOLYGON(((...))) | Bréhan | 56024 | +{% endhighlight %} + +#### 4. Case with `deleteTable` + +Import the `city.shp` layer into the `CITY` table +{% highlight mysql %} +CALL SHPRead('/home/user/CITY.shp', 'CITY'); +{% endhighlight %} + +Now, import once again `city.shp`, using `deleteTable`=`true` +{% highlight mysql %} +CALL SHPRead('/home/user/city.shp', 'CITY', true); +{% endhighlight %} +Returns : `null` (= no errors, the table `CITY` has been replaced). + +Then, import once again `city.shp`, using `deleteTable`=`false` +{% highlight mysql %} +CALL SHPRead('/home/user/city.shp', 'CITY', false); {% endhighlight %} +Returns : `The table "CITY" already exists` ##### See also diff --git a/docs/dev/SHPWrite.md b/docs/dev/SHPWrite.md index 31b5f7f706..2362e82f7a 100644 --- a/docs/dev/SHPWrite.md +++ b/docs/dev/SHPWrite.md @@ -13,21 +13,26 @@ permalink: /docs/dev/SHPWrite/ {% highlight mysql %} SHPWrite(VARCHAR path, VARCHAR tableName); +SHPWrite(VARCHAR path, VARCHAR tableName, BOOLEAN deleteTable); SHPWrite(VARCHAR path, VARCHAR tableName, VARCHAR fileEncoding); +SHPWrite(VARCHAR path, VARCHAR tableName, + VARCHAR fileEncoding, BOOLEAN deleteTable); {% endhighlight %} ### Description -Writes the contents of table `tableName` to a [shapefile][wiki] +Writes the content of table `tableName` into a [shapefile][wiki] located at `path`. `tablename` can be either: * the name of an existing table, -* the result of a query (`SELECT` instruction which has to be written between simple quote and parenthesis `'( )'`). +* the result of a query (`SELECT` instruction which has to be written between simple quote and parenthesis `'( )'`). **Warning**: when using text value in the `WHERE` condition, you have to double the simple quote (different from double quote ""): `... WHERE TextColumn = ''myText''`. +Define `fileEncoding` to force encoding (useful when the header is missing encoding information) (default value is `ISO-8859-1`). -The default value of `fileEncoding` is `ISO-8859-1`. + +If the `deleteTable` parameter is `true` and if the specified `shapefile` already exists at the `path` address, then the `shapefile` will be removed / replaced by the new one. Else (no `deleteTable` parameter or `deleteTable` equal to `false`), an error indicating that the `shapefile` already exists will be throwned.
Shapefiles do not support arbitrary geometrical data.
@@ -42,12 +47,19 @@ The default value of `fileEncoding` is `ISO-8859-1`. ### Examples +In the following example, we are working with a table named `AREA` and defined as follow. + {% highlight mysql %} --- Create an example table containing POLYGONs and export it. -CREATE TABLE AREA(THE_GEOM GEOMETRY, ID INT PRIMARY KEY); +CREATE TABLE AREA(THE_GEOM GEOMETRY(POLYGON), ID INT); INSERT INTO AREA VALUES ('POLYGON((-10 109, 90 9, -10 9, -10 109))', 1), ('POLYGON((90 109, 190 9, 90 9, 90 109))', 2); +{% endhighlight %} + + +#### 1. Case with `path` and `tablename` + +{% highlight mysql %} CALL SHPWrite('/home/user/area.shp', 'AREA'); -- Read it back, showing that the driver wrote POLYGONs as @@ -61,7 +73,7 @@ SELECT * FROM AREA2; -- | MULTIPOLYGON(((90 109, 190 109, 90 9, 90 109))) | 2 | {% endhighlight %} -#### Case where `tablename` is the result of a selection. +#### 2. Case where `tablename` is the result of a selection {% highlight mysql %} CALL SHPWRITE('/home/user/area.shp', @@ -76,6 +88,32 @@ SELECT * FROM AREA2; -- | MULTIPOLYGON(((-10 109,, 90 9, -10 9, -10 109))) | 1 | {% endhighlight %} +#### Case with `deleteTable` + +Export the table `AREA` into the `area.shp` file. + +{% highlight mysql %} +CALL SHPWRITE('/home/user/area.shp', 'AREA'); +{% endhighlight %} + +The `area.shp` is created. + +Now write once again, using the `deleteTable` = `true` + +{% highlight mysql %} +CALL SHPWRITE('/home/user/area.shp', 'AREA', true); +{% endhighlight %} + +The existing `area.shp` file is removed and replaced by the new one. + +Now, same but with `deleteTable` = `false` + +{% highlight mysql %} +CALL SHPWRITE('/home/user/area.shp', 'AREA', false); +{% endhighlight %} + +A message is thrown: `The file already exist`. + ### Export the .prj file If you want to export your shapefile with it's projection, stored in a .prj file, you must assume that the table contains a SRID constraint value greater than 0. diff --git a/docs/dev/ST_AsGeoJson.md b/docs/dev/ST_AsGeoJson.md index 6463a09b10..d94970b209 100644 --- a/docs/dev/ST_AsGeoJson.md +++ b/docs/dev/ST_AsGeoJson.md @@ -22,19 +22,32 @@ Both 2D and 3D Geometries are supported. ### Examples +#### Case with a `POINT` + {% highlight mysql %} SELECT ST_AsGeoJSON('POINT(1 2)'); --- Answer: {"type":"Point","coordinates":[1.0,2.0]} - -SELECT ST_AsGeoJSON('POLYGON((101 345 1, 300 345 2, 300 100 2, - 101 100 2, 101 345 1), - (130 300 2, 190 300 2, 190 220 2, - 130 220 2, 130 300 2))'); --- Answer: {"type":"Polygon", "coordinates":[[[101.0, 345.0, 1.0], --- [300.0, 345.0, 2.0], [300.0, 100.0, 2.0], [101.0, 100.0, 2.0], --- [101.0, 345.0, 1.0]], --- [[130.0, 300.0, 2.0], [190.0, 300.0, 2.0], [190.0, 220.0, 2.0], --- [130.0, 220.0, 2.0], [130.0, 300.0, 2.0]]]} +{% endhighlight %} + +Answer: +{% highlight xml %} +{"type":"Point","coordinates":[1.0,2.0]} +{% endhighlight %} + +#### Case with a `POLYGON` + +{% highlight mysql %} +SELECT ST_AsGeoJSON('POLYGON + (101 345 1, 300 345 2, 300 100 2,101 100 2, 101 345 1), + (130 300 2, 190 300 2, 190 220 2, 130 220 2, 130 300 2))'); +{% endhighlight %} + +Answer: +{% highlight xml %} +{"type":"Polygon","coordinates":[[[101.0,345.0,1.0], + [300.0,345.0,2.0],[300.0,100.0,2.0],[101.0,100.0,2.0], + [101.0,345.0,1.0]],[[130.0,300.0,2.0],[190.0,300.0,2.0], + [190.0,220.0,2.0],[130.0,220.0,2.0],[130.0,300.0,2.0]]] +} {% endhighlight %} ##### See also diff --git a/docs/dev/ST_AsKML.md b/docs/dev/ST_AsKML.md index 1a21e34ac4..7d1f68ccfb 100644 --- a/docs/dev/ST_AsKML.md +++ b/docs/dev/ST_AsKML.md @@ -20,58 +20,97 @@ VARCHAR ST_AsKML(GEOMETRY geom, BOOLEAN extrude, INT altitudeMode); Converts `geom` to its [KML][wiki] representation. -Supported values of `altitudeMode`: + +The `extrude` parameter *"specifies whether to connect the LinearRing to the ground. To extrude this geometry, the altitude mode must be either `relativeToGround`, `relativeToSeaFloor`, or `absolute`. Only the vertices of the LinearRing are extruded, not the center of the geometry. The vertices are extruded toward the center of the Earth's sphere."* ([Source](https://developers.google.com/kml/documentation/kmlreference)) + + +The `altitudeMode` parameter is used to specify a distance above the ground level, sea level, or sea floor ([See more](https://developers.google.com/kml/documentation/kmlreference)). The supported values of `altitudeMode` are: | Value | Meaning | -|-------|----------------------| -| 0 | none | -| 1 | `clampToGround` | -| 2 | `relativeToGround` | -| 4 | `absolute` | -| 8 | `clampToSeaFloor` | -| 16 | `relativeToSeaFloor` | +|:-----:|:--------------------:| +| 0 | none | +| 1 | `clampToGround` | +| 2 | `relativeToGround` | +| 4 | `absolute` | +| 8 | `clampToSeaFloor` | +| 16 | `relativeToSeaFloor` | ### Examples +#### 1. Case with `geom` + {% highlight mysql %} SELECT ST_AsKML(ST_GeomFromText('POINT(2.19 47.58), 4326')); --- Answer: --- 2.19,47.58 --- +{% endhighlight %} + +Answer: +{% highlight xml %} + + 2.19,47.58 + +{% endhighlight %} + +#### 2. Case with `altitudeMode` = `clampToGround` + +{% highlight mysql %} SELECT ST_AsKML(ST_GeomFromText('POINT(2.19 47.58), 4326'), TRUE, 1); --- Answer: --- 1 --- clampToGround --- 2.19,47.58 --- +{% endhighlight %} + +Answer: +{% highlight xml %} + + 1 + clampToGround + 2.19,47.58 + +{% endhighlight %} + +#### 3. Case with `altitudeMode` = `relativeToSeaFloor` + +{% highlight mysql %} SELECT ST_AsKML(ST_GeomFromText('POINT(2.19 47.58), 4326'), FALSE, 16); --- Answer: --- 0 --- relativeToSeaFloor --- 2.19,47.58 --- +{% endhighlight %} + +Answer: + +{% highlight xml %} + + 0 + relativeToSeaFloor + 2.19,47.58 + +{% endhighlight %} + +#### 4. Case with `altitudeMode` = `relativeToGround` +{% highlight mysql %} SELECT ST_AsKML( - ST_GeomFromText('LINESTRING(-1.53 47.24 100, -1.51 47.22 100, - -1.50 47.19 100, -1.49 47.17 100)', + ST_GeomFromText('LINESTRING(-1.53 47.24 100, -1.51 47.22 100, + -1.50 47.19 100, -1.49 47.17 100)', 4326), TRUE, 2); --- Answer: --- 1 --- relativeToGround --- --- -1.53,47.24,100.0 -1.51,47.22,100.0 -1.5, --- 47.19,100.0 -1.49,47.17,100.0 --- --- +{% endhighlight %} + +Answer: + +{% highlight xml %} + + 1 + relativeToGround + + -1.53,47.24,100.0 -1.51,47.22,100.0 -1.5, + 47.19,100.0 -1.49,47.17,100.0 + + {% endhighlight %} ##### See also +* [`KMLWrite`](../KMLWrite) * Source code [wiki]: http://en.wikipedia.org/wiki/Keyhole_Markup_Language diff --git a/docs/dev/ST_OSMDownloader.md b/docs/dev/ST_OSMDownloader.md index 39a9dcfcaa..f5cf7d0242 100644 --- a/docs/dev/ST_OSMDownloader.md +++ b/docs/dev/ST_OSMDownloader.md @@ -18,7 +18,7 @@ ST_OSMDownloader(GEOMETRY geom, VARCHAR path, BOOLEAN delete); ### Description -Download data from the [OSM][wiki] api using a bounding box (`geom`). The result is stored in an .osm file which the place and the name are defined in the `path`. If the `delete` parameter is equal to one (true), then the .osm file will be overwritten if it already exists. +Download data from the [OSM][wiki] API using a bounding box (`geom`). The result is stored in an `.osm` file which the place and the name are defined in the `path`. If the `delete` parameter is equal to `true`, then the `.osm` file will be overwritten if it already exists. ### Examples @@ -48,7 +48,7 @@ On the left a screenshot from the [OpenStreetMap](http://www.openstreetmap.org) ##### See also -* [`OSMRead`](../OSMRead) +* [`OSMRead`](../OSMRead), [`ST_OSMMapLink`](../ST_OSMMapLink) * Source code [wiki]: http://wiki.openstreetmap.org/wiki/OSM_XML diff --git a/docs/dev/ST_OSMMapLink.md b/docs/dev/ST_OSMMapLink.md index 84183b69dd..62ca71d1af 100644 --- a/docs/dev/ST_OSMMapLink.md +++ b/docs/dev/ST_OSMMapLink.md @@ -41,19 +41,25 @@ Use case with the Castle of Nantes, which coordinates are exprimed in the French ##### Case without `marker` {% highlight mysql %} -SELECT ST_OSMMAPLINK(ST_TRANSFORM(ST_SETSRID(THE_GEOM, 2154), 4326)) as URL FROM NANTES_CASTLE; - --- Answer: http://www.openstreetmap.org/?minlon=-1.550246541734283&minlat=47.21546462871126&maxlon=-1.5479838062318023&maxlat=47.21682348531568 +SELECT ST_OSMMAPLINK( + ST_TRANSFORM(ST_SETSRID(THE_GEOM, 2154), 4326) + ) as URL FROM NANTES_CASTLE; {% endhighlight %} + +Answer: [http://www.openstreetmap.org/?minlon=-1.550246541734283&minlat=47.21546462871126&maxlon=-1.5479838062318023&maxlat=47.21682348531568](http://www.openstreetmap.org/?minlon=-1.550246541734283&minlat=47.21546462871126&maxlon=-1.5479838062318023&maxlat=47.21682348531568) + ##### Case with `marker` {% highlight mysql %} -SELECT ST_OSMMAPLINK(ST_TRANSFORM(ST_SETSRID(THE_GEOM, 2154), 4326), true) as URL FROM NANTES_CASTLE; - --- Answer: http://www.openstreetmap.org/?minlon=-1.550246541734283&minlat=47.21546462871126&maxlon=-1.5479838062318023&maxlat=47.21682348531568&mlat=47.216144057013466&mlon=-1.5491151739830427 +SELECT ST_OSMMAPLINK( + ST_TRANSFORM(ST_SETSRID(THE_GEOM, 2154), 4326), true + ) as URL FROM NANTES_CASTLE; {% endhighlight %} + +Answer: [http://www.openstreetmap.org/?minlon=-1.550246541734283&minlat=47.21546462871126&maxlon=-1.5479838062318023&maxlat=47.21682348531568&mlat=47.216144057013466&mlon=-1.5491151739830427](http://www.openstreetmap.org/?minlon=-1.550246541734283&minlat=47.21546462871126&maxlon=-1.5479838062318023&maxlat=47.21682348531568&mlat=47.216144057013466&mlon=-1.5491151739830427) + ##### See also diff --git a/docs/dev/ST_SRID.md b/docs/dev/ST_SRID.md index 6fb6b6663f..8f11153657 100644 --- a/docs/dev/ST_SRID.md +++ b/docs/dev/ST_SRID.md @@ -34,6 +34,5 @@ SELECT ST_SRID(ST_GeomFromText('LINESTRING(2 1, 1 3, 5 2, 2 1)', ##### See also -* [`ST_SetSRID`](../ST_SetSRID), -[`ST_GeomFromText`](../ST_GeomFromText) +* [`ST_SetSRID`](../ST_SetSRID), [`UpdateGeometrySRID`](../UpdateGeometrySRID), [`ST_Transform`](../ST_Transform), [`ST_GeomFromText`](../ST_GeomFromText) * Source code \ No newline at end of file diff --git a/docs/dev/ST_Transform.md b/docs/dev/ST_Transform.md index b6d4235eca..0ec1b89c38 100644 --- a/docs/dev/ST_Transform.md +++ b/docs/dev/ST_Transform.md @@ -5,7 +5,7 @@ category: geom2D/projections is_function: true description: Transform a Geometry from one CRS to another prev_section: ST_SetSRID -next_section: geom2D/properties +next_section: UpdateGeometrySRID permalink: /docs/dev/ST_Transform/ --- @@ -40,4 +40,7 @@ SELECT ST_Transform(ST_GeomFromText( ##### See also + + +* [`ST_SetSRID`](../ST_SetSRID), [`UpdateGeometrySRID`](../UpdateGeometrySRID), [`ST_SRID`](../ST_SRID) * Source code diff --git a/docs/dev/TSVRead.md b/docs/dev/TSVRead.md index 472ba531de..88d72eef37 100644 --- a/docs/dev/TSVRead.md +++ b/docs/dev/TSVRead.md @@ -13,15 +13,26 @@ permalink: /docs/dev/TSVRead/ {% highlight mysql %} TSVRead(VARCHAR path); +TSVRead(VARCHAR path, BOOLEAN deleteTable); TSVRead(VARCHAR path, VARCHAR tableName); +TSVRead(VARCHAR path, VARCHAR tableName, BOOLEAN deleteTable); +TSVRead(VARCHAR path, VARCHAR tableName, VARCHAR fileEncoding); +TSVRead(VARCHAR path, VARCHAR tableName, + VARCHAR fileEncoding, BOOLEAN deleteTable); {% endhighlight %} ### Description -Reads the file specified by `path` as a Tab-Separated Values ([TSV][wiki]) file and -copies its contents into a new table `tableName` in the database. +Reads the file specified by `path` as a Tab-Separated Values ([TSV][wiki]) file and copies its contents into a new table `tableName` in the database. -If the `tablename` parameter is not specified, then the resulting table has the same name as the TSV file. +This `.tsv` file may be zipped in a `.gz` file *(in this case, the `TSVRead` driver will unzip on the fly the `.gz` file)*. + +Define `fileEncoding` to force encoding (useful when the header is missing encoding information) (default value is `ISO-8859-1`). + +If: + +- the `tablename` parameter is not specified, then the resulting table has the same name as the TSV file. +- the `deleteTable` parameter is `true` and table `tableName` already exists in the database, then table `tableName` will be removed / replaced by the new one. Else (no `deleteTable` parameter or `deleteTable` equal to `false`), an error indicating that the table `tableName` already exists will be throwned.
Warning on the input file name
@@ -30,6 +41,8 @@ If the `tablename` parameter is not specified, then the resulting table has the ### Example +##### 1. Case with `path` and `tableName` + In following example, we have a TSV file, which is stored here : `/home/user/GoT.tsv`. This file is structured as follow. {% highlight mysql %} @@ -54,6 +67,48 @@ SELECT * FROM GameOfThrones ; -- | Baelish | Peter | King's Landing | {% endhighlight %} +#### 2. Case with a `.gz` file + +{% highlight mysql %} +CALL TSVRead('/home/user/GoT.tsv.gz'); +{% endhighlight %} + +→ Here, since there is no `tableName` parameter, `GoT.tsv.gz` will produce a table named `GOT_TSV`. + +#### 3. Case with `fileEncoding` + +{% highlight mysql %} +CALL TSVRead('/home/user/GoT.tsv', 'GameOfThrones', 'utf-8'); +{% endhighlight %} + +→ Here the resulting `GameOfThrones` table is encoded in `utf-8` + +#### 4. Case with `deleteTable` + +Load the `GoT.tsv` file +{% highlight mysql %} +CALL TSVRead('/home/user/GoT.tsv'); +{% endhighlight %} + +→ the table `GOT` is created. + +Now, load once again, using `deleteTable` = `true` + +{% highlight mysql %} +CALL TSVRead('/home/user/GoT.tsv', true); +{% endhighlight %} + +→ the already existing `GOT` table is removed / replaced. + +Now, load once again, using `deleteTable` = `false` + +{% highlight mysql %} +CALL TSVRead('/home/user/GoT.tsv', false); +{% endhighlight %} + +→ Error message: `The table "GOT" already exists`. + + ##### See also * [`TSVWrite`](../TSVWrite) diff --git a/docs/dev/TSVWrite.md b/docs/dev/TSVWrite.md index 60a3326647..5807da0c68 100644 --- a/docs/dev/TSVWrite.md +++ b/docs/dev/TSVWrite.md @@ -13,12 +13,27 @@ permalink: /docs/dev/TSVWrite/ {% highlight mysql %} TSVWrite(VARCHAR path, VARCHAR tableName); +TSVWrite(VARCHAR path, VARCHAR tableName, BOOLEAN deleteTable); +TSVWrite(VARCHAR path, VARCHAR tableName, VARCHAR fileEncoding); +TSVWrite(VARCHAR path, VARCHAR tableName, + VARCHAR fileEncoding, BOOLEAN deleteTable); {% endhighlight %} ### Description Save a table (`tablename`) into a Tab-Separated Values ([TSV][wiki]) file specified by `path`. +`tableName` can be either: + +* the name of an existing table, +* the result of a query (`SELECT` instruction which has to be written between simple quote and parenthesis `'( )'`). **Warning**: when using text value in the `WHERE` condition, you have to double the simple quote (different from double quote ""): `... WHERE TextColumn = ''myText''`. + +The `.tsv` file may be zipped in a `.gz` file *(in this case, the `TSVWrite` driver will zip on the fly the `.tsv` file)*. + +Define `fileEncoding` to force encoding (useful when the header is missing encoding information) (default value is `ISO-8859-1`). + +If the `deleteTable` parameter is `true` and `path` file already exists, then `path` file will be removed / replaced by the new one. Else (no `deleteTable` parameter or `deleteTable` equal to `false`), an error indicating that the `path` file already exists will be throwned. + ### Example In following example, we have a table called `GameOfThrones` and structured as follow. @@ -34,6 +49,8 @@ SELECT * FROM GameOfThrones ; -- | Baelish | Peter | King's Landing | {% endhighlight %} +#### 1. Case with `path` and `tableName` + Now we save this table into a .tsv file ... {% highlight mysql %} CALL TSVWrite('/home/user/GoT.tsv', 'GameOfThrones'); @@ -49,6 +66,57 @@ Snow Jon Castle Black Baelish Peter King's Landing {% endhighlight mysql %} +If you want to compress your resulting `.tsv` file into a `.gz` file, just execute + +{% highlight mysql %} +CALL TSVWrite('/home/user/GoT.tsv.gz', 'GameOfThrones'); +{% endhighlight mysql %} + +As a result, you will obtain a `GoT.tsv.gz` file in which there is the `GoT.tsv` resulting file. + + +#### 2. Case where `tableName` is the result of a selection + +{% highlight mysql %} +CALL TSVWrite('/home/user/GoT.tsv', + '(SELECT * FROM GAMEOFTHRONES WHERE NAME=''Stark'')'); + +-- Read it back: +CALL TSVRead('/home/user/GoT.tsv', 'GOT2'); +SELECT * FROM GOT2; +-- Answer: +-- | NAME | FIRSTNAME | PLACE | +-- |-------|-----------|------------| +-- | Stark | Arya | Winterfell | +{% endhighlight %} + + + + +#### 3. Case with `fileEncoding` + +{% highlight mysql %} +CALL TSVWrite('/home/user/GoT.tsv', 'GameOfThrones', 'utf-8'); +{% endhighlight %} + +#### 4. Case with `deleteTable` +We condisder that the `Got.tsv` already exists here `/home/user/` +{% highlight mysql %} +CALL TSVWrite('/home/user/GoT.tsv', 'GameOfThrones', true); +-- or +CALL TSVWrite('/home/user/GoT.tsv', 'GameOfThrones', 'utf-8', true); +{% endhighlight %} +Since we have `deleteTable` = `true`, the file `Got.tsv` is overwritten. + +Now, execute with `deleteTable` = `false` +{% highlight mysql %} +CALL TSVWrite('/home/user/GoT.tsv', 'GameOfThrones', false); +-- or +CALL TSVWrite('/home/user/GoT.tsv', 'GameOfThrones', 'utf-8', false); +{% endhighlight %} + +An error message is throwned: `The tsv file already exists` + ##### See also * [`TSVRead`](../TSVRead) diff --git a/docs/dev/UpdateGeometrySRID.md b/docs/dev/UpdateGeometrySRID.md new file mode 100644 index 0000000000..d172a6d3f1 --- /dev/null +++ b/docs/dev/UpdateGeometrySRID.md @@ -0,0 +1,56 @@ +--- +layout: docs +title: UpdateGeometrySRID +category: geom2D/projections +is_function: true +description: Update the SRID of a geometry column +prev_section: ST_Transform +next_section: geom2D/properties +permalink: /docs/dev/UpdateGeometrySRID/ +--- + +### Signatures + +{% highlight mysql %} +BOOLEAN UpdateGeometrySRID(VARCHAR tableName, + GEOMETRY geom, + INT srid); +{% endhighlight %} + +### Description + +Updates the `srid` of all features in a geometry column (`geom`) from a table (`tableName`). + +Returns `TRUE` if the `srid` has been updated. + +
+
UpdateGeometrySRID does not to actually change the projection of geom. + For this purpose, use ST_Transform.
+
+ + +### Examples + +{% highlight mysql %} +-- Create a table and insert a POINT with a SRID equal to 0 +CREATE TABLE GEO_POINT (THE_GEOM GEOMETRY(POINT)); +INSERT INTO GEO_POINT VALUES('SRID=0;POINT(0 0)'); + +-- Check the SRID +SELECT ST_SRID(THE_GEOM) as SRID FROM GEO_POINT; +-- Answer: SRID = 0 + +--------------------------- +-- Update the SRID +SELECT UpdateGeometrySRID('GEO_POINT','THE_GEOM',4326); + +-- And check the SRID +SELECT ST_SRID(THE_GEOM) as SRID FROM GEO_POINT; +-- Answer: SRID = 4326 +{% endhighlight %} + + +##### See also + +* [`ST_Transform`](../ST_Transform), [`ST_SRID`](../ST_SRID), [`ST_SetSRID`](../ST_SetSRID) +* Source code