From 3c6ad3782aab0c0ea4bcffca647aff527b179cce Mon Sep 17 00:00:00 2001
From: Timm Fitschen <t.fitschen@indiscale.com>
Date: Tue, 12 Dec 2023 14:58:06 +0100
Subject: [PATCH] DOC: update POV docs
---
procedures/query/applyPOV.sql | 22 ++++++++++------------
procedures/query/initPOV.sql | 10 ++++++++--
procedures/query/initSubEntity.sql | 14 ++++----------
3 files changed, 22 insertions(+), 24 deletions(-)
diff --git a/procedures/query/applyPOV.sql b/procedures/query/applyPOV.sql
index 0dce57f..47532bc 100644
--- a/procedures/query/applyPOV.sql
+++ b/procedures/query/applyPOV.sql
@@ -36,31 +36,29 @@ DELIMITER //
* versioned : boolean
* If True, sourceSet and targetSet have an _iversion column, otherwise that column will be ignored
* (or only HEAD will be inserted into targetSet).
-
-
- TODO description of sourceSet and targetSet is insufficient!
*/
-CREATE PROCEDURE db_5_0.applyPOV(in sourceSet VARCHAR(255), /* (?) Name of the table that the POV will be applied to. This can be a temporary table. */
- in targetSet VARCHAR(255), /* (?) Name of the result table of this POV. */
+CREATE PROCEDURE db_5_0.applyPOV(in sourceSet VARCHAR(255), /* Name of the table that the POV will be applied to. This can be a temporary table or the `entities` table */
+ in targetSet VARCHAR(255), /* Name of the result table of this POV. After the filter has been applied this table only contains matching
+ entity ids. This may be NULL or same as sourceSet. In that case the filter is applied in-place (delete non-matching). Otherwise the filter is applied by copying only the matching ids from the *source* set to the *target* set. */
in propertiesTable VARCHAR(255),
- in refIdsTable VARCHAR(255), /* (?) Name of a tmp table that contains all ids of children of the value interpreted as entity */
+ in refIdsTable VARCHAR(255), /* Name of a tmp table that contains all ids of children of the value interpreted as entity name or id */
in o CHAR(4), /* The operator for this operation. can be one of:
0 check for "equals NULL"
!0 check for "not NULL"
-> check whether a reference exists
- ( (?) check for datetime intervals
- !( (?) check for being outside of datetime intervals
- other operators (all SQL operators (?))
+ ( check for datetime interval (say "in")
+ !( check for being outside of datetime intervals (say "not in")
+ other operators (all valid SQL operators)
these other operators can be used either with or without an aggregation
to use an aggregation set agg to non-zero
all SQL aggregations can be used
*/
- in vText VARCHAR(255), /* (?) the text value to be checked against using operator o */
+ in vText VARCHAR(255), /* the text value to be checked against using operator o */
in vInt INT, /* the integer value to be checked against using operator o */
in vDouble DOUBLE, /* the double value to be checked against using operator o */
- in unit_sig BIGINT,
+ in unit_sig BIGINT, /* signatur of the unit given by the user. used when we need to convert units. */
in vDoubleStdUnit DOUBLE, /* The numeric value, converted according to the unit rules. */
- in stdUnit_sig BIGINT,
+ in stdUnit_sig BIGINT, /* signatur of the normalized/standardized unit, e.g when unit_sig is "km/h" this might be "m/s". */
in vDateTime VARCHAR(255),
in vDateTimeDotNotation VARCHAR(255),
in agg CHAR(3), /* an SQL aggregate function or NULL when no aggregation should be used */
diff --git a/procedures/query/initPOV.sql b/procedures/query/initPOV.sql
index 377bc98..2afdc9c 100644
--- a/procedures/query/initPOV.sql
+++ b/procedures/query/initPOV.sql
@@ -60,8 +60,14 @@ BEGIN
SELECT conv( concat( substring(uid,16,3), substring(uid,10,4), substring(uid,1,8)),16,10) div 10000 - (141427 * 24 * 60 * 60 * 1000) as current_mills INTO t1 from (select uuid() uid) as alias;
call createTmpTable2(propertiesTable);
- -- fill in all properties named "PropertyName"
- -- what are overwrites needed for?
+ -- Fill in all properties (plus the domain id and entity id) named
+ -- "PropertyName", be it their default name or their overridden name.
+ -- We need *all* properties (mind, the properties of entities not
+ -- abstract properties) with the given name. If an abstract
+ -- property has the name "person" it might have the name "author" in
+ -- the "Article" record type. Now, if I want to collect all properties
+ -- of the Article named "author" I need to look into the name_overrides
+ -- table.
SET @initPOVPropertiesTableStmt1 = CONCAT('INSERT IGNORE INTO `', propertiesTable, '` (id, id2, domain) SELECT property_id, entity_id, domain_id from name_overrides WHERE name = ? UNION ALL SELECT entity_id, domain_id, 0 FROM name_data WHERE value = ?;');
PREPARE stmt FROM @initPOVPropertiesTableStmt1;
SET @PropertyName = PropertyName;
diff --git a/procedures/query/initSubEntity.sql b/procedures/query/initSubEntity.sql
index 67484d0..d542b33 100644
--- a/procedures/query/initSubEntity.sql
+++ b/procedures/query/initSubEntity.sql
@@ -25,16 +25,10 @@ DROP PROCEDURE IF EXISTS db_5_0.initSubEntity;
DELIMITER //
/*
-* This procedures composes a table with the ids of all entities with the given
- * name and all their children (!!)
-* and if provided adds the supplied entity id.
-*
-* The table name has to be provided.
-*/
-
-/*
- * Initialize a new temporary table by loading an entity and all of its children
- * into the table (i.e. their internal ids).
+ * Initialize a new temporary table by loading an entity (by name or by id or
+ * both) and all of its children into the table (i.e. their internal ids).
+ *
+ * The table name has to be provided.
*
* This is used by initPOVRefidsTable and initBackReference for sub-property filtering.
*
--
GitLab