diff --git a/docs/src/50-mbtiles.md b/docs/src/50-mbtiles.md new file mode 100644 index 000000000..e7921404f --- /dev/null +++ b/docs/src/50-mbtiles.md @@ -0,0 +1,3 @@ +# MBTiles + +Martin has a few additional [tools](51-tools.md) that can be used to interact with [MBTiles](https://github.com/mapbox/mbtiles-spec). diff --git a/docs/src/50-tools.md b/docs/src/51-tools.md similarity index 74% rename from docs/src/50-tools.md rename to docs/src/51-tools.md index e0d5ec06c..e917a2323 100644 --- a/docs/src/50-tools.md +++ b/docs/src/51-tools.md @@ -1,7 +1,3 @@ -# Tools - -Martin has a few additional tools that can be used to interact with the data. - ## MBTiles tool A small utility that allows users to interact with the `*.mbtiles` files from the command line. Use `mbtiles --help` to see a list of available commands, and `mbtiles --help` to see help for a specific command. @@ -84,56 +80,4 @@ Per-tile validation will catch individual invalid tiles, but it will not detect For that, Martin `mbtiles` tool defines a new metadata value called `agg_tiles_hash`. The value is computed by hashing `cast(zoom_level AS text), cast(tile_column AS text), cast(tile_row AS text), tile_data` combined for all rows in the `tiles` table/view, ordered by z,x,y. In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if `tile_data` accidentally contains non-blob/text/null value, validation will fail. -The `mbtiles` tool will compute `agg_tiles_hash` value when copying or validating mbtiles files. - -## Supported Schema -The `mbtiles` tool supports three different kinds of schema for `tiles` data in `.mbtiles` files. See also the original [specification](https://github.com/mapbox/mbtiles-spec#readme). - -### flat -```sql, ignore -CREATE TABLE tiles (zoom_level integer, tile_column integer, tile_row integer, tile_data blob); -CREATE UNIQUE INDEX tile_index on tiles (zoom_level, tile_column, tile_row); -``` - -### flat-with-hash -```sql, ignore -CREATE TABLE tiles_with_hash ( - zoom_level integer NOT NULL, - tile_column integer NOT NULL, - tile_row integer NOT NULL, - tile_data blob, - tile_hash text); -CREATE UNIQUE INDEX tiles_with_hash_index on tiles_with_hash (zoom_level, tile_column, tile_row); -CREATE VIEW tiles AS SELECT zoom_level, tile_column, tile_row, tile_data FROM tiles_with_hash; -``` - -### normalized -```sql, ignore -CREATE TABLE map (zoom_level INTEGER, tile_column INTEGER, tile_row INTEGER, tile_id TEXT); -CREATE UNIQUE INDEX map_index ON map (zoom_level, tile_column, tile_row); -CREATE TABLE images (tile_id text, tile_data blob); -CREATE UNIQUE INDEX images_id ON images (tile_id); -CREATE VIEW tiles AS - SELECT - map.zoom_level AS zoom_level, - map.tile_column AS tile_column, - map.tile_row AS tile_row, - images.tile_data AS tile_data - FROM map - JOIN images ON images.tile_id = map.tile_id; -``` - -Optionally, `.mbtiles` files with `normalized` schema can include a `tiles_with_hash` view: - -```sql, ignore -CREATE VIEW tiles_with_hash AS - SELECT - map.zoom_level AS zoom_level, - map.tile_column AS tile_column, - map.tile_row AS tile_row, - images.tile_data AS tile_data, - images.tile_id AS tile_hash - FROM map LEFT JOIN images ON map.tile_id = images.tile_id; -``` - -**__Note:__** All `normalized` files created by the `mbtiles` tool will contain this view. +The `mbtiles` tool will compute `agg_tiles_hash` value when copying or validating mbtiles files. \ No newline at end of file diff --git a/docs/src/52-schemas.md b/docs/src/52-schemas.md new file mode 100644 index 000000000..eb1e36359 --- /dev/null +++ b/docs/src/52-schemas.md @@ -0,0 +1,51 @@ +## Supported Schema +The `mbtiles` tool supports three different kinds of schema for `tiles` data in `.mbtiles` files. See also the original [specification](https://github.com/mapbox/mbtiles-spec#readme). + +### flat +```sql, ignore +CREATE TABLE tiles (zoom_level integer, tile_column integer, tile_row integer, tile_data blob); +CREATE UNIQUE INDEX tile_index on tiles (zoom_level, tile_column, tile_row); +``` + +### flat-with-hash +```sql, ignore +CREATE TABLE tiles_with_hash ( + zoom_level integer NOT NULL, + tile_column integer NOT NULL, + tile_row integer NOT NULL, + tile_data blob, + tile_hash text); +CREATE UNIQUE INDEX tiles_with_hash_index on tiles_with_hash (zoom_level, tile_column, tile_row); +CREATE VIEW tiles AS SELECT zoom_level, tile_column, tile_row, tile_data FROM tiles_with_hash; +``` + +### normalized +```sql, ignore +CREATE TABLE map (zoom_level INTEGER, tile_column INTEGER, tile_row INTEGER, tile_id TEXT); +CREATE UNIQUE INDEX map_index ON map (zoom_level, tile_column, tile_row); +CREATE TABLE images (tile_id text, tile_data blob); +CREATE UNIQUE INDEX images_id ON images (tile_id); +CREATE VIEW tiles AS + SELECT + map.zoom_level AS zoom_level, + map.tile_column AS tile_column, + map.tile_row AS tile_row, + images.tile_data AS tile_data + FROM map + JOIN images ON images.tile_id = map.tile_id; +``` + +Optionally, `.mbtiles` files with `normalized` schema can include a `tiles_with_hash` view: + +```sql, ignore +CREATE VIEW tiles_with_hash AS + SELECT + map.zoom_level AS zoom_level, + map.tile_column AS tile_column, + map.tile_row AS tile_row, + images.tile_data AS tile_data, + images.tile_id AS tile_hash + FROM map LEFT JOIN images ON map.tile_id = images.tile_id; +``` + +**__Note:__** All `normalized` files created by the `mbtiles` tool will contain this view. diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index 018f59937..468af83a4 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -21,5 +21,7 @@ - [Using with deck.gl](43-using-with-deck-gl.md) - [Using with Mapbox](44-using-with-mapbox.md) - [Recipes](45-recipes.md) -- [Tools](50-tools.md) +- [MBTiles](50-mbtiles.md) + - [Tools](51-tools.md) + - [Supported Schemas](52-schemas.md) - [Development](60-development.md)