maps

One row per map (site plan, floor plan, or other spatial reference). Identified by id; lives on a single project. Carries metadata about the map file — the image itself is not stored here.

Source Mapping

CouchDB document type: a "map" document (see asyncconvert.py's maps(obj) handler).

Column	CouchDB source	Notes
id	id	Map identifier; unique within the dataset across projects (project-scoped semantics — see Pitfalls).
name	name	Human-readable map name. Free text.
groupid	groupId	The map_groups.id this map belongs to. May be empty when the map is ungrouped.
groupname	group	Denormalized group name from source — convenient but can drift from map_groups.name.
author	content.author	Email of the user who uploaded / authored the map.
creationdate	dates.creationDate	Parsed via parseDate(...).
lastmodifieddate	dates.lastModifiedDate	Parsed via parseDate(...).
archived	archived	Parsed via parseDate(...). NULL for active maps.
projectid	database	The project this map belongs to.
couchdbid	couchDbId	Legacy CouchDB document identifier.

The maps table does not carry pixel or geographic coordinates. Spatial positioning of tickets on a map is captured on tickets.x, tickets.y, tickets.latitude, and tickets.longitude.

Column Reference

Column	Type	Nullable	Description
archived	DATETIME	yes	Archive timestamp; NULL for active maps.
author	VARCHAR(255)	yes	Email of the user who authored / uploaded the map.
creationdate	DATETIME	yes	When the map was created upstream.
lastmodifieddate	DATETIME	yes	When the upstream map was last edited.
groupid	VARCHAR(255)	yes	Foreign-key reference to map_groups.id.
groupname	VARCHAR(255)	yes	Denormalized group name; convenience copy of map_groups.name from source.
name	TEXT	yes	Human-readable map name (free text).
id	VARCHAR(255)	no	Primary key. Map identifier; project-scoped (see Pitfalls).
projectid	VARCHAR(255)	yes	The project this map belongs to.
couchdbid	VARCHAR(255)	yes	Legacy CouchDB identifier.

Keys

• Primary key: id

Indexes

• idx_project on projectid

Relationships

Direction	Other table	Join	Cardinality
outgoing	map_groups	maps.groupid = map_groups.id	many maps → one group
outgoing	projects	maps.projectid = projects.id	many maps → one project
outgoing	users (author)	maps.author = users.email	many maps → one author
incoming	audits_maps	audits_maps.mapid = maps.id	one map → many audit links
incoming	tickets	tickets.map = maps.id	one map → many tickets placed on it

None of these are foreign-keyed in MariaDB; joins are by string match.

Refresh Semantics

A row is upserted when its map document is observed in source data, and replaced on subsequent observations. Archive is a soft state: the archived DATETIME is set when the map is archived upstream, but the row is not removed and existing tickets and audits that reference it continue to resolve.

A reindex with type=map (or a full reindex) drops the maps table and rebuilds it from source. See backend/services/sql.py for the drop and setup paths.

Common Queries

List active maps on a project

SELECT id, name, groupname, creationdate
FROM maps
WHERE projectid = 'your_project_id'
  AND archived IS NULL
ORDER BY name;

Find archived maps

SELECT id, name, groupname, archived
FROM maps
WHERE projectid = 'your_project_id'
  AND archived IS NOT NULL
ORDER BY archived DESC;

Maps by author

SELECT
  author,
  COUNT(*) AS maps_uploaded
FROM maps
WHERE archived IS NULL
GROUP BY author
ORDER BY maps_uploaded DESC;

Cross-table queries (audits per map, tickets per map, maps grouped by their map group) live on the Maps domain landing.

Pitfalls

• id is project-scoped, not global. Two projects each with a "Ground Floor" map produce two maps rows with two different id values. Joining on id does not give you cross-project usage — group by name for that, with the usual free-text caveats.
• groupname can drift from map_groups.name. It is a denormalized copy from source. If the group is renamed, the authoritative value is map_groups.name; groupname may lag until the map document is re-synced.
• No spatial data on this table. The map's pixel and geo coordinates do not live here. Tickets carry (x, y) and (latitude, longitude) for their position on the map.
• No FK constraints. groupid, projectid, and author are joined by string match. If an upstream group is deleted without maps being re-synced, groupid may point to a missing map_groups row.