Wildcards + and *

What this is about

Every time you read data, you tell CDMS in the response list which fields you want back. You can name every field one by one. For models with many fields this is tedious, so there are two shortcuts, the wildcards:

The example model

All pictures on this page use the same model employee:

The two basic forms

POST /api/rest/hr/employee/read/7f3…
{ "response": ["*"] }

{
  "data": {
    "id": "7f3…",
    "firstname": "Daniel",
    "lastname": "Mertins",
    "company":    { "id": "a1…", "companyname": null },
    "department": { "id": "d4…", "name": null }
  },
  "meta": { "error": false }
}

If you need more than the id of a reference, you expand it explicitly. This is explained under Expand references.

The partial wildcards

You can combine both characters with the start or the end of a word. The character goes either at the very front or at the very end:

How CDMS resolves a wildcard

A component in the REST layer, the Expander, does the resolving. For each entry of the response list it works like this:

flowchart TB
    E["Entry from response"] --> Q1{"Is it an object<br/>{ field, response }?"}
    Q1 -->|yes| R["Expand the reference explicitly<br/>(separate page)"]
    Q1 -->|no| Q2{"Does the text contain<br/>+ or * at the start<br/>or at the end?"}
    Q2 -->|no| F["take exactly this field"]
    Q2 -->|"yes, +"| P["all simple fields<br/>whose name matches"]
    Q2 -->|"yes, *"| S["all simple fields whose name matches<br/>+ all references whose name matches<br/>(only with id)"]
    P --> X["subtract exclude"]
    S --> X
    F --> Z["Result: list of fields<br/>→ exactly these columns are read from the DB"]
    X --> Z

Four rules you should remember:

1. Start or end of a word, nothing else. There are no regular expressions, no character in the middle of a word, and never two characters in one entry.
2. Upper and lower case matter. +Name does not match firstname.
3. Several entries are added together. ["+name", "*ment"] returns firstname, lastname and department.
4. No match is not an error. A wildcard that matches nothing simply returns no fields, and the response is still 200.

Removing fields again: exclude

With exclude you remove single fields from the result of a wildcard:

{ "response": ["*"], "exclude": ["department"] }

{ "data": { "id": "7f3…", "firstname": "Daniel",
            "lastname": "Mertins", "company": { "id": "a1…" },
            "department": null } }

All variants at a glance

The two traps

Trap 1: null does not mean “empty”

The response always contains the whole object. Fields you did not request appear as null, they are not missing. So with firstname: null you do not know whether the field is empty or whether you just did not request it.

Trap 2: * needs the permissions of all references

A ["*"] that works for you can fail for a colleague who has fewer roles.

Why all this? The effect on the database

The response is not a filter that removes fields from the response afterwards. It already decides what is read from the database: CDMS builds a query that reads exactly the requested columns and attaches references with a LEFT JOIN. So a + on a model with 40 fields reads 40 columns, ["id", "name"] only two.

flowchart LR
    A["response: ['id','firstname','*ment']"] --> B["Expander<br/>→ id, firstname, department.id"]
    B --> C["SQL: SELECT e.id, e.firstname, d.id<br/>FROM employee e<br/>LEFT JOIN department d …"]
    C --> D["Response with exactly these values"]