Modul:Entity/Store
Weitere Optionen
| Function list |
|---|
| L 23 — bucketLib L 65 — rowFor L 92 — selfRow L 99 — p.selfUuid L 115 — p.selfValue L 138 — p.selfValues L 164 — p.pageValue L 197 — p.resolveUuids L 230 — p.resolvePages L 261 — p.count |
Entitys eigene Leseschicht für gespeicherte Entity-Daten: die UUID der aktuellen Seite, ein gespeicherter Wert der aktuellen Seite sowie die UUID-zu-Seite- und Seite-zu-Zusammenfassung-Lookups, die die Entity-Renderer brauchen. Reads folgen der Backend-Wahl von Modul:Entity/StructuredData: Modul:Entity/Store/Smw für SMW, das hier installierte Standard.
Die generische Schicht — welche Tabelle und Spalte eine Eigenschaft beherbergt und wie eine Abfrage aus Eigenschaftsnamen gebaut wird — liegt in Modul:BucketQuery.
Für Modul-Editoren
API
selfUuid(): die für die aktuelle Seite gespeicherte UUID, nil bis zum ersten Link-Update.selfValue(displayName, kind): der eigene gespeicherte Wert einer Eigenschaft der aktuellen Seite.resolveUuids(list): UUID zu{ page, image }, in 50er-Batches.resolvePages(list): Seitentitel zu{ name, manufacturer, role, image }, in 50er-Batches; ein Batch-Fehler ist im Inneren enthalten (leere Map für den Batch).count({ filters, kind }): die Anzahl der passenden Zeilen, nil beim fehlgeschlagenen Read. Auf SMW antwortet einmw.smw.askmitformat=countserverseitig.resolve,needsKindundquerysind aus Modul:BucketQuery re-exportiert.
Erweitern
Ein Verbraucher, der kein Entity-Code ist, sollte Modul:BucketQuery direkt requiren statt in diesen Namensraum zu greifen. Die Re-Exports existieren für Entitys eigene Module. Modul:RentalVehicleGrid ist der eine Nicht-Entity-Verbraucher, der hierher gehört, weil er resolvePages für eine Entity-Fahrzeugzusammenfassung ruft.
Stolperfallen
- Der SMW-Leser nutzt
Module:Entity/Store/Smw.batchLimitals Batch-Größe (Standard 500) und folgt Continuation-Offsets. Er spiegelt den Bucket-Fehlervertrag:selfUuid/selfValuedegradieren zu nil undresolvePageszu leerem Beitrag, wenn die SMW-Abfrageschicht versagt, während die eigenen Validierungsfehler und das lautequery/resolveUuidsweiter werfen. - SMW-Filter unterstützen Gleichheit, Präsenz, Kategorien, ODER-Listen von Kategorien und ODER-Listen von Gleichheits-Alternativen auf einer Eigenschaft; jedes andere ODER-Shape scheitert laut statt unvollständig zurückzukehren.
- Mengenprintouts kommen als Wert/Einheit-Tabellen zurück und werden nur für die sondegesicherten Paare konvertiert (u. a.
quantum_speedin m/s, Treibstoffkapazitäten in SCU). - Jeder Read hier ist auf den Hauptnamensraum bewacht; ohne sie griffe eine gleichbetitelte
Vorlage:-Seite die Zeile der Hauptnamensraum-Entität. imagewird normalisiert: der SMW-Schreiber speichertDatei:<name>, der Leser strippt das Präfix zurück zum nackten Dateinamen.
require('strict')
--- @module Entity/Store
--- Entity's own read layer for stored Entity data: the current page's uuid, one
--- stored value for the current page, and the uuid-to-page and page-to-summary
--- lookups the Entity renderers need. The public readers dispatch per
--- Module:Entity/StructuredData's backend selection: this file's Bucket
--- queries, or Module:Entity/Store/Smw. The Bucket implementation roots on the
--- `entity` bucket literally, which is what makes it Entity's rather than shared.
---
--- The generic layer -- which table and column a property lives in, and how a
--- query is built from property names -- is Module:BucketQuery. `resolve`,
--- `needsKind` and `query` are re-exported here so Entity's own callers have one
--- module to reach for; a consumer that is NOT Entity code should require
--- Module:BucketQuery directly rather than reaching into this namespace.
local BucketQuery = require('Module:BucketQuery')
--- Bucket's callable library. Resolved when a query runs, never at module load:
--- requiring `mw.ext.bucket` returns a fresh, non-callable copy of the library on
--- the wiki, and the bare `bucket` global fails the undeclared-global scan.
--- @return table
local function bucketLib()
return mw.ext.bucket
end
local p = {}
-- Every query below is about Entity pages, so the bucket is named, not defaulted.
local PRIMARY = 'entity'
-- One `where` per uuid, so a batch is bounded by Bucket's condition budget
-- rather than by the caller's list length.
local UUID_BATCH = 50
-- Room for every title that differs from one page's only in case, all of which
-- a case-insensitive `page_name` match returns.
local CASE_VARIANTS = 10
-- Bucket has no count aggregate, so a count selects the rows and counts them;
-- the limit is Bucket's own row ceiling, not a tuning knob. The SMW half
-- counts server-side instead, so this cap is a Bucket-only bound.
local COUNT_LIMIT = 5000
-- Re-exported from Module:BucketQuery; see the note above on which module a
-- consumer should require.
p.resolve = BucketQuery.resolve
p.needsKind = BucketQuery.needsKind
p.query = BucketQuery.query
--- One page's row from `bucket`, or nil for a page off the main namespace:
--- Bucket rows exist only for main-namespace pages, so without this guard a
--- same-titled Talk:/Template:/... page would match the mainspace entity's
--- row, and `title.text` equals `page_name` only for namespace 0. Wrapped in
--- `pcall`: a Bucket infrastructure failure (rate limit, timeout) degrades to
--- nil rather than red-erroring the page, which is also the documented answer
--- for "no row yet". Bucket compares `page_name` case-insensitively, so the
--- `where` also returns the rows of titles that differ only in case (the
--- FrostBite cooler answers for the Frostbite settlement); only the row whose
--- `page_name` is exactly this title is the page's own.
--- @param title table|nil a mw.title
--- @param bucket string
--- @param field string
--- @return table|nil
local function rowFor(title, bucket, field)
if not title or title.namespace ~= 0 then
return nil
end
local ok, raw = pcall(function()
return bucketLib()(bucket)
.select('page_name', field)
.where({ 'page_name', '=', title.text })
.limit(CASE_VARIANTS)
.run()
end)
if not ok or type(raw) ~= 'table' then
return nil
end
for _, row in ipairs(raw) do
if row.page_name == title.text then
return row
end
end
return nil
end
--- The current page's own row from `bucket`; shared by selfUuid, selfValue and
--- selfValues so they do not duplicate the query.
--- @param bucket string
--- @param field string
--- @return table|nil
local function selfRow(bucket, field)
return rowFor(mw.title.getCurrentTitle(), bucket, field)
end
--- The uuid stored for the current page, available after its first link
--- update. Runs on every {{Entity}} invocation.
--- @return string|nil
function p.selfUuid()
local row = selfRow(PRIMARY, 'uuid')
if row and type(row.uuid) == 'string' and row.uuid ~= '' then
return row.uuid
end
return nil
end
--- The current page's own stored value of `displayName` (resolved through
--- resolve(), so a per-kind property needs `kind`), nil until its first link
--- update has run. nil when `displayName` does not resolve, or when the row's
--- value is neither a non-empty string nor a number (e.g. a repeated field's
--- array, or absent).
--- @param displayName string
--- @param kind string|nil
--- @return string|number|nil
function p.selfValue(displayName, kind)
local entry = p.resolve(displayName, kind)
if entry == nil then
return nil
end
local row = selfRow(entry.bucket, entry.field)
local value = row and row[entry.field]
if type(value) == 'string' and value ~= '' then
return value
end
if type(value) == 'number' then
return value
end
return nil
end
--- The current page's own stored values for a REPEATED property, as a list.
--- A repeated field comes back as an array, which selfValue deliberately
--- rejects, so a caller that wants one needs this instead. nil until the page's
--- first link update has run, and nil when the row holds no usable value.
--- @param displayName string
--- @param kind string|nil
--- @return string[]|nil
function p.selfValues(displayName, kind)
local entry = p.resolve(displayName, kind)
if entry == nil then
return nil
end
local row = selfRow(entry.bucket, entry.field)
local value = row and row[entry.field]
if type(value) ~= 'table' then
return nil
end
local out = {}
for _, item in ipairs(value) do
if type(item) == 'string' and item ~= '' then
out[#out + 1] = item
end
end
return out[1] and out or nil
end
--- Another page's stored value of `displayName` (resolved through resolve(),
--- so a per-kind property needs `kind`), nil when the page is not in the main
--- namespace, has no row, or holds neither a non-empty string nor a number.
--- @param page string|nil
--- @param displayName string
--- @param kind string|nil
--- @return string|number|nil
function p.pageValue(page, displayName, kind)
if type(page) ~= 'string' or page == '' then
return nil
end
local entry = p.resolve(displayName, kind)
if entry == nil then
return nil
end
-- Rows are keyed by the page a redirect lands on: StructuredData stores a
-- PAGE value as its redirect target. Reading `redirectTarget` loads the
-- page and records a templatelinks edge to it, so editing the target page
-- queues a refresh of every page naming it here (for the CURRENT page,
-- Scribunto instead varies the cached render by that page's revision
-- SHA1, rather than adding that edge).
local title = mw.title.new(page)
if title and title.redirectTarget then
title = title.redirectTarget
end
local row = rowFor(title, entry.bucket, entry.field)
local value = row and row[entry.field]
if type(value) == 'string' and value ~= '' then
return value
end
if type(value) == 'number' then
return value
end
return nil
end
--- Maps uuids to their page and infobox image. Bucket rows exist only for
--- main-namespace pages (the write-side rule), so no namespace check is needed.
--- @param uuids string[]
--- @return table<string, { page: string, image: string|nil }>
function p.resolveUuids(uuids)
local map = {}
for start = 1, #uuids, UUID_BATCH do
local conds = {}
for i = start, math.min(start + UUID_BATCH - 1, #uuids) do
conds[#conds + 1] = { 'uuid', '=', uuids[i] }
end
-- 2x headroom: a duplicate-uuid page (a known live condition) needs a
-- second slot per uuid before a batch starts truncating.
local raw = bucketLib()(PRIMARY)
.select('uuid', 'page_name', 'image')
.where(bucketLib().Or(unpack(conds)))
.limit(#conds * 2)
.run()
for _, r in ipairs(type(raw) == 'table' and raw or {}) do
if type(r.uuid) == 'string' and type(r.page_name) == 'string' and not map[r.uuid] then
local image = r.image
if type(image) ~= 'string' or image == '' then
image = nil
end
map[r.uuid] = { page = r.page_name, image = image }
end
end
end
return map
end
--- Rows for the given page titles (vehicle readers): manufacturer, role and
--- image keyed by page name. Batches of UUID_BATCH equalities; a Bucket
--- failure yields an empty map for that batch, contained in `pcall` here
--- rather than left to the caller (unlike resolveUuids).
--- @param names string[]
--- @return table<string, { name: string|nil, manufacturer: string|nil, role: string|nil, image: string|nil }>
function p.resolvePages(names)
local map = {}
for start = 1, #names, UUID_BATCH do
local conds = {}
for i = start, math.min(start + UUID_BATCH - 1, #names) do
conds[#conds + 1] = { 'page_name', '=', names[i] }
end
local ok, raw = pcall(function()
return bucketLib()(PRIMARY)
.select('page_name', 'name', 'manufacturer', 'image', 'vehicle.role')
.join('vehicle', 'vehicle.page_name', PRIMARY .. '.page_name')
.where(bucketLib().Or(unpack(conds)))
.limit(#conds)
.run()
end)
for _, r in ipairs((ok and type(raw) == 'table') and raw or {}) do
if type(r.page_name) == 'string' then
map[r.page_name] =
{ name = r.name, manufacturer = r.manufacturer, role = r['vehicle.role'], image = r.image }
end
end
end
return map
end
--- The number of rows the filters match, or nil when the read failed. Bucket
--- has no count aggregate, so this selects page names up to Bucket's row
--- ceiling and counts them; a set larger than the ceiling answers the ceiling,
--- and the SMW half is the one that counts exactly.
--- @param spec { filters: (string|table)[], kind: string|nil }
--- @return number|nil
function p.count(spec)
-- Mirrors the SMW half's unbounded-query rejection: an unfiltered count of
-- the whole entity bucket is never what a caller means.
if type(spec.filters) ~= 'table' or #spec.filters == 0 then
error('Store: unbounded count')
end
local ok, rows = pcall(p.query, {
filters = spec.filters,
kind = spec.kind,
columns = { { builtin = 'page_name', as = 'page' } },
limit = COUNT_LIMIT,
})
if not ok or type(rows) ~= 'table' then
return nil
end
local n = 0
for _ in ipairs(rows) do
n = n + 1
end
return n
end
-- The same setting selects both halves of Entity storage.
for _, name in ipairs({
'selfUuid',
'selfValue',
'selfValues',
'pageValue',
'resolveUuids',
'resolvePages',
'query',
'count',
}) do
local bucketMethod = p[name]
p[name] = function(...)
local backend = require('Module:Entity/StructuredData').backend()
if backend == 'bucket' then
return bucketMethod(...)
elseif backend == 'smw' then
return require('Module:Entity/Store/Smw')[name](...)
end
error('Unknown structured-data backend: ' .. tostring(backend))
end
end
-- Test-only exports. Not part of the public API. The manifest override lives on
-- Module:BucketQuery, which owns the manifests; it is re-exported so a suite
-- testing Entity's helpers does not need to require both modules.
p._internal = {
setManifests = BucketQuery._internal.setManifests,
}
return p

