summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorThiago Marcos P. Santos <tmpsantos@gmail.com>2019-10-10 20:53:58 +0300
committerThiago Marcos P. Santos <tmpsantos@gmail.com>2019-10-11 16:06:28 +0300
commita4e1707f6b0b6610284e30b5068050f90ede9ae4 (patch)
treea7651f1f2b5f9e825c3d970a7a9e0a12794cdfa6
parent990fdc43facab2d296f35bc8670a926d05fbe864 (diff)
downloadqtlocation-mapboxgl-a4e1707f6b0b6610284e30b5068050f90ede9ae4.tar.gz
[offline] Document the database schema
-rw-r--r--platform/default/include/mbgl/storage/offline_schema.sql164
1 files changed, 134 insertions, 30 deletions
diff --git a/platform/default/include/mbgl/storage/offline_schema.sql b/platform/default/include/mbgl/storage/offline_schema.sql
index 722b0e0451..93f6f2a5ce 100644
--- a/platform/default/include/mbgl/storage/offline_schema.sql
+++ b/platform/default/include/mbgl/storage/offline_schema.sql
@@ -1,55 +1,159 @@
-CREATE TABLE resources ( -- Generic table for style, source, sprite, and glyph resources.
- id INTEGER NOT NULL PRIMARY KEY AUTOINCREMENT,
- url TEXT NOT NULL,
- kind INTEGER NOT NULL,
- expires INTEGER,
- modified INTEGER,
- etag TEXT,
- data BLOB,
- compressed INTEGER NOT NULL DEFAULT 0,
- accessed INTEGER NOT NULL,
- must_revalidate INTEGER NOT NULL DEFAULT 0,
+--
+-- Table containing the style, source, sprite, and glyph
+-- resources. Essentially everything that is not a tile.
+--
+CREATE TABLE resources (
+ id INTEGER NOT NULL PRIMARY KEY AUTOINCREMENT, -- Primary key.
+
+ url TEXT NOT NULL, -- The URL of the resource without the access token. If a Mapbox
+ -- resource, will be stored using the mapbox:// schema. Must be
+ -- unique and that is enforced by the database schema.
+
+ kind INTEGER NOT NULL, -- Type of the resource, taken from Resource::Kind enumeration:
+ -- style = 1
+ -- source = 2
+ -- tile = 3
+ -- glyphs = 4
+ -- sprite image = 5
+ -- sprite JSON = 6
+ -- image = 7
+
+ expires INTEGER, -- Expiration time. The resource will be refreshed after this
+ -- expiration is reached.
+
+ modified INTEGER, -- Last time the resource was modified.
+
+ etag TEXT, -- Checksum used for cache optimization. If, when refreshing the
+ -- resource, it matches the etag on the server, the resource will
+ -- not get re-downloaded. See:
+ -- https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag
+
+ data BLOB, -- Contents of the resource.
+
+ compressed INTEGER NOT NULL DEFAULT 0, -- If the resource is compressed with Deflate or not. Compression is
+ -- optional and should be used when the compression ratio is
+ -- significant. Using compression will make decoding time slower
+ -- because it will add an extra decompression step.
+
+ accessed INTEGER NOT NULL, -- Last time the resource was used by GL Native. Useful for when
+ -- evicting the least used resources from the cache.
+
+ must_revalidate INTEGER NOT NULL DEFAULT 0, -- When set to true, the resource will not be used unless it gets
+ -- first revalidated by the server.
UNIQUE (url)
);
+--
+-- Table containing all tiles, both vector and raster.
+--
CREATE TABLE tiles (
- id INTEGER NOT NULL PRIMARY KEY AUTOINCREMENT,
- url_template TEXT NOT NULL,
- pixel_ratio INTEGER NOT NULL,
- z INTEGER NOT NULL,
- x INTEGER NOT NULL,
- y INTEGER NOT NULL,
- expires INTEGER,
- modified INTEGER,
- etag TEXT,
- data BLOB,
- compressed INTEGER NOT NULL DEFAULT 0,
- accessed INTEGER NOT NULL,
- must_revalidate INTEGER NOT NULL DEFAULT 0,
+ id INTEGER NOT NULL PRIMARY KEY AUTOINCREMENT, -- Primary key.
+
+ url_template TEXT NOT NULL, -- The URL of the resource without the access token and without
+ -- the tiles id substituted. Mapbox tiles will be stored using
+ -- the mapbox:// schema. Example:
+ -- mapbox://tiles/user.dataset/{z}/{x}/{y}.vector.pbf
+
+ pixel_ratio INTEGER NOT NULL, -- The tile pixel ratio, typically 1 for vector tiles.
+
+ z INTEGER NOT NULL, -- The zoom level of the tile.
+
+ x INTEGER NOT NULL, -- The x position of the tile on the tile grid.
+
+ y INTEGER NOT NULL, -- The y position of the tile on the tile grid.
+
+ expires INTEGER, -- Expiration time. The tile will be refreshed after this
+ -- expiration is reached. Expired tiles can still be rendered,
+ -- unless must_revalidate is set to true. If an expired tile
+ -- gets rendered, it will be replaced by a newer version as soon
+ -- as the network request with a new tile arrives.
+
+ modified INTEGER, -- Last time the tile was modified.
+
+ etag TEXT, -- Checksum used for cache optimization. If, when refreshing the
+ -- tile, it matches the etag on the server, the tile will not
+ -- get re-downloaded. See:
+ -- https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag
+
+ data BLOB, -- Contents of the tile.
+
+ compressed INTEGER NOT NULL DEFAULT 0, -- If the tile is compressed with Deflate or not. Compression is
+ -- optional and should be used when the compression ratio is
+ -- significant. Using compression will make decoding time slower
+ -- because it will add an extra decompression step.
+
+ accessed INTEGER NOT NULL, -- Last time the tile was used by GL Native. Useful for when
+ -- evicting the least used tiles from the cache.
+
+ must_revalidate INTEGER NOT NULL DEFAULT 0, -- When set to true, the tile will not be used unless it gets
+ -- first revalidated by the server.
UNIQUE (url_template, pixel_ratio, z, x, y)
);
+--
+-- Regions define the offline regions, which could be a GeoJSON geometry,
+-- or a bounding box like this example:
+--
+-- {
+-- "bounds": [
+-- 37.2,
+-- -122.8,
+-- 38.1,
+-- -121.7
+-- ],
+-- "include_ideographs": false,
+-- "max_zoom": 15.0,
+-- "min_zoom": 0.0,
+-- "pixel_ratio": 1.0,
+-- "style_url": "mapbox://styles/mapbox/streets-v11"
+-- }
+--
+-- The semantic definition of the region is up to the user and
+-- it could be a city, a country or an arbitrary bounding box.
+--
+-- Regions can overlap, which will cause them to share resources
+-- when it is the case.
+--
+-- "include_ideographs" is set to true when CJK characters are
+-- include on the offline package. By default, CJK is rendered
+-- by GL Native client side using local fonts. Downloading CJK
+-- will increase the size of the database considerably.
+--
CREATE TABLE regions (
- id INTEGER NOT NULL PRIMARY KEY AUTOINCREMENT,
- definition TEXT NOT NULL, -- JSON formatted definition of region. Regions may be of variant types:
- -- e.g. bbox and zoom range, route path, flyTo parameters, etc. Note that
- -- the set of tiles required for a region may span multiple sources.
- description BLOB -- User provided data in user-defined format
+ id INTEGER NOT NULL PRIMARY KEY AUTOINCREMENT, -- Primary key.
+
+ definition TEXT NOT NULL, -- JSON formatted definition of a region, a bounding box
+ -- or a GeoJSON geometry. See https://geojson.org.
+
+ description BLOB -- User provided data in user-defined format.
);
+--
+-- Table mapping resources to regions. A resource
+-- might be part of many regions. Resources without
+-- regions are part of the ambient cache.
+--
CREATE TABLE region_resources (
region_id INTEGER NOT NULL REFERENCES regions(id) ON DELETE CASCADE,
resource_id INTEGER NOT NULL REFERENCES resources(id),
UNIQUE (region_id, resource_id)
);
+--
+-- Table mapping tiles to regions. A tile might
+-- be part of many regions, meaning that regions might
+-- overlap efficiently. Tiles without regions are part
+-- of the ambient cache.
+--
CREATE TABLE region_tiles (
region_id INTEGER NOT NULL REFERENCES regions(id) ON DELETE CASCADE,
tile_id INTEGER NOT NULL REFERENCES tiles(id),
UNIQUE (region_id, tile_id)
);
--- Indexes for efficient eviction queries
+--
+-- Indexes for efficient eviction queries.
+--
CREATE INDEX resources_accessed
ON resources (accessed);