diff --git a/.vitepress/config.js b/.vitepress/config.js index 0bfab873f3..4b10f941fc 100644 --- a/.vitepress/config.js +++ b/.vitepress/config.js @@ -194,10 +194,12 @@ if (process.env.VITE_CAPIRE_EXTRA_ASSETS) { import { dl } from '@mdit/plugin-dl' import * as MdAttrsPropagate from './lib/md-attrs-propagate' import * as MdTypedModels from './lib/md-typed-models' +import * as MdDiagramSvg from './lib/md-diagram-svg' config.markdown.config = md => { MdAttrsPropagate.install(md) MdTypedModels.install(md) + MdDiagramSvg.install(md) md.use(dl) } diff --git a/.vitepress/lib/md-diagram-svg.ts b/.vitepress/lib/md-diagram-svg.ts new file mode 100644 index 0000000000..fdcfccccd0 --- /dev/null +++ b/.vitepress/lib/md-diagram-svg.ts @@ -0,0 +1,22 @@ +import { MarkdownEnv, MarkdownRenderer } from 'vitepress' +import { readFileSync } from 'node:fs'; +import { dirname, join } from 'node:path'; + +export function install(md: MarkdownRenderer) { + const defaultImage = + md.renderer.rules.image || + ((tokens, idx, options, env, self) => self.renderToken(tokens, idx, options)) + + md.renderer.rules.image = (tokens, idx, options, env: MarkdownEnv, self) => { + const token = tokens[idx] + const src = token.attrGet('src') || '' + + if (!/\.svg\?raw$/.test(src)) { + return defaultImage(tokens, idx, options, env, self) + } + const mdDir = dirname(env.realPath ?? env.path) + const filePath = join(mdDir, src.replace('?raw', '')) + const content = readFileSync(filePath, 'utf-8') + return `${content}` + } +} diff --git a/.vitepress/theme/styles.scss b/.vitepress/theme/styles.scss index 2989dbbbde..78846f49bd 100644 --- a/.vitepress/theme/styles.scss +++ b/.vitepress/theme/styles.scss @@ -312,6 +312,18 @@ img, video.bright { } } +// Raw svg diagrams +.diagram { + all: initial; // preserve original svg formatting + .dark & { // recolor in dark mode + filter: brightness(.884) invert(1) hue-rotate(177deg); + } + svg { + max-width: 100%; + height: auto; + margin: 30px auto; + } +} .VPBadge { diff --git a/cds/assets/cql/nested-expand.drawio.svg b/cds/assets/cql/nested-expand.drawio.svg new file mode 100644 index 0000000000..d5a130ce06 --- /dev/null +++ b/cds/assets/cql/nested-expand.drawio.svg @@ -0,0 +1,347 @@ + + + + + + + + + + +
+
+
+ + { + +
+
+
+ + + { + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ + } + +
+
+
+ + + } + + + + + + + + + + + +
+
+
+ select item +
+
+
+ + + select item + + + + + + + + + + + +
+
+
+ + , + +
+
+
+ + + , + + + + + + + + + + + + + + + +
+
+
+ EXCLUDING +
+
+
+ + + EXCLUDING + + + + + + + + + + + +
+
+
+ + } + +
+
+
+ + + } + + + + + + + + + + + +
+
+
+ + { + +
+
+
+ + + { + + + + + + + + + + + +
+
+
+ identifier +
+
+
+ + + identifier + + + + + + + + + + + +
+
+
+ + , + +
+
+
+ + + , + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ path expression +
+
+
+ + + path expression + + + + + + + + + + + + + + + +
+
+
+ AS +
+
+
+ + + AS + + + + + + + + + + + +
+
+
+ alias +
+
+
+ + + alias + + + + + + + + + + + + + + + + + + + + + + + + + + Text is not SVG - cannot display + + + + \ No newline at end of file diff --git a/cds/assets/cql/nested-inline.drawio.svg b/cds/assets/cql/nested-inline.drawio.svg new file mode 100644 index 0000000000..d559daf9b2 --- /dev/null +++ b/cds/assets/cql/nested-inline.drawio.svg @@ -0,0 +1,320 @@ + + + + + + + + + + +
+
+
+ + { + +
+
+
+ + + { + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ + } + +
+
+
+ + + } + + + + + + + + + + + +
+
+
+ select item +
+
+
+ + + select item + + + + + + + + + + + +
+
+
+ + , + +
+
+
+ + + , + + + + + + + + + + + + + + + +
+
+
+ EXCLUDING +
+
+
+ + + EXCLUDING + + + + + + + + + + + +
+
+
+ + } + +
+
+
+ + + } + + + + + + + + + + + +
+
+
+ + { + +
+
+
+ + + { + + + + + + + + + + + +
+
+
+ identifier +
+
+
+ + + identifier + + + + + + + + + + + +
+
+
+ + , + +
+
+
+ + + , + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ + . + +
+
+
+ + + . + + + + + + + + + + + +
+
+
+ path expression +
+
+
+ + + path expression + + + + + + + + + + + + + + + + + + Text is not SVG - cannot display + + + + \ No newline at end of file diff --git a/cds/assets/cql/ordering-term.drawio.svg b/cds/assets/cql/ordering-term.drawio.svg new file mode 100644 index 0000000000..a3ad2b3acd --- /dev/null +++ b/cds/assets/cql/ordering-term.drawio.svg @@ -0,0 +1,201 @@ + + + + + + + + + + + + + + + + + expr + + + + + + + + + + + +
+
+
+ ASC +
+
+
+ + + ASC + + + + + + + + + + + +
+
+
+ DESC +
+
+
+ + + DESC + + + + + + + + + + + +
+
+
+ NULLS +
+
+
+ + + NULLS + + + + + + + + + + + +
+
+
+ FIRST +
+
+
+ + + FIRST + + + + + + + + + + + +
+
+
+ NULLS +
+
+
+ + + NULLS + + + + + + + + + + + +
+
+
+ LAST +
+
+
+ + + LAST + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Text is not SVG - cannot display + + + + \ No newline at end of file diff --git a/cds/assets/cql/postfix-projection.drawio.svg b/cds/assets/cql/postfix-projection.drawio.svg new file mode 100644 index 0000000000..ee228ee4e1 --- /dev/null +++ b/cds/assets/cql/postfix-projection.drawio.svg @@ -0,0 +1,272 @@ + + + + + + + + + + +
+
+
+ + { + +
+
+
+ + + { + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ + } + +
+
+
+ + + } + + + + + + + + + + + +
+
+
+ select item +
+
+
+ + + select item + + + + + + + + + + + +
+
+
+ + , + +
+
+
+ + + , + + + + + + + + + + + + + + + +
+
+
+ EXCLUDING +
+
+
+ + + EXCLUDING + + + + + + + + + + + +
+
+
+ + } + +
+
+
+ + + } + + + + + + + + + + + +
+
+
+ + { + +
+
+
+ + + { + + + + + + + + + + + +
+
+
+ identifier +
+
+
+ + + identifier + + + + + + + + + + + +
+
+
+ + , + +
+
+
+ + + , + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Text is not SVG - cannot display + + + + \ No newline at end of file diff --git a/cds/assets/cql/query-source.drawio.svg b/cds/assets/cql/query-source.drawio.svg new file mode 100644 index 0000000000..5e2043a7d7 --- /dev/null +++ b/cds/assets/cql/query-source.drawio.svg @@ -0,0 +1,271 @@ + + + + + + + + + + + FQN + + + + + + + + + + + + + + +
+
+
+ path expression +
+
+
+ + + path expression + + + + + + + + + + + +
+
+
+ identifier +
+
+
+ + + identifier + + + + + + + + + + + +
+
+
+ + : + +
+
+
+ + + : + + + + + + + + + + + +
+
+
+ AS +
+
+
+ + + AS + + + + + + + + + + + +
+
+
+ alias +
+
+
+ + + alias + + + + + + + + + + + +
+
+
+ namespace +
+
+
+ + + namespace + + + + + + + + + + + +
+
+
+ infix filter +
+
+
+ + + infix filter + + + + + + + + + + + +
+
+
+ + . + +
+
+
+ + + . + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Text is not SVG - cannot display + + + + \ No newline at end of file diff --git a/cds/assets/cql/select-item.drawio.svg b/cds/assets/cql/select-item.drawio.svg new file mode 100644 index 0000000000..8ce4e83204 --- /dev/null +++ b/cds/assets/cql/select-item.drawio.svg @@ -0,0 +1,365 @@ + + + + + + + + + + nested inline + + + + + + + + + + nested expand + + + + + + + + + + +
+
+
+ AS +
+
+
+ + + AS + + + + + + + + + + + +
+
+
+ expr +
+
+
+ + + expr + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ alias +
+
+
+ + + alias + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ path expression +
+
+
+ + + path expression + + + + + + + + + + + +
+
+
+ + : + +
+
+
+ + + : + + + + + + + + + + + +
+
+
+ type +
+
+
+ + + type + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ postfix projection +
+
+
+ + + postfix projection + + + + + + + + + + + + + + + +
+
+
+ AS +
+
+
+ + + AS + + + + + + + + + + + +
+
+
+ alias +
+
+
+ + + alias + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ + . + +
+
+
+ + + . + + + + + + + + + + + +
+
+
+ + postfix projection + +
+
+
+ + + postfix projection + + + + + + + + + + + +
+
+
+ path expression +
+
+
+ + + path expression + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Text is not SVG - cannot display + + + + \ No newline at end of file diff --git a/cds/assets/cql/select.drawio.svg b/cds/assets/cql/select.drawio.svg new file mode 100644 index 0000000000..d007018730 --- /dev/null +++ b/cds/assets/cql/select.drawio.svg @@ -0,0 +1,477 @@ + + + + + + + + + + + postfix projection + + + + + + + + + + + SELECT + + + + + + + + + + FROM + + + + + + + + + + + query source + + + + + + + + + + + { + + + + + + + + + + + + + + + + + + + + + + } + + + + + + + + + + + select item + + + + + + + + + + + , + + + + + + + + + + + + + + EXCLUDING + + + + + + + + + + } + + + + + + + + + + { + + + + + + + + + + identifier + + + + + + + + + + , + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + WHERE + + + + + + + + + + + + + + expr + + + + + + + + + + + , + + + + + + + + + + + + + + + + + + + + + + + + + + GROUP BY + + + + + + + + + + + + + + expr + + + + + + + + + + + , + + + + + + + + + + + + + + + + + + + + + + HAVING + + + + + + + + + + + + + + expr + + + + + + + + + + + , + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ORDER BY + + + + + + + + + + + + + ordering term + + + + + + + + + + , + + + + + + + + + + + + + + + + + + + + + + + + + + LIMIT + + + + + + + + + + + expr + + + + + + + + + + + OFFSET + + + + + + + + + + + expr + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/cds/cql.md b/cds/cql.md index 3e2abae87e..7c7d2f9892 100644 --- a/cds/cql.md +++ b/cds/cql.md @@ -14,9 +14,27 @@ CDS Query Language (CQL) is based on standard SQL, which it enhances by... [[toc]] +## SELECT + +![](./assets/cql/select.drawio.svg?raw) + +> Using: [Query Source](#query-source), [Select Item](#select-item), [Expressions](./cxl#expr), Ordering Term + + +## Query Source + +![](./assets/cql/query-source.drawio.svg?raw) + +## Select Item + +![](./assets/cql/select-item.drawio.svg?raw) + + ## Postfix Projections {#postfix-projections} +![](./assets/cql/postfix-projection.drawio.svg?raw) + CQL allows to put projections, that means, the `SELECT` clause, behind the `FROM` clause enclosed in curly braces. For example, the following are equivalent: ```sql @@ -29,6 +47,10 @@ SELECT from Authors { name, address.street } ### Nested Expands {#nested-expands} + +![](./assets/cql/nested-expand.drawio.svg?raw) + + Postfix projections can be appended to any column referring to a struct element or an association and hence be nested. This allows **expand** results along associations and hence read deeply structured documents: @@ -125,6 +147,8 @@ results = [ ### Nested Inlines {#nested-inlines} +![](./assets/cql/nested-inline.drawio.svg?raw) + Put a **`"."`** before the opening brace to **inline** the target elements and avoid writing lengthy lists of paths to read several elements from the same target. For example: ```sql @@ -466,3 +490,8 @@ extend BookReviews with columns { book : Association to Books on book.ID = bookID }; ``` + + +## Ordering Term + +![](./assets/cql/ordering-term.drawio.svg?raw)