X-Git-Url: https://gerrit.onap.org/r/gitweb?a=blobdiff_plain;f=docs%2Fcps-path.rst;h=bc46681d1cb72de953d80ed8c7d99499cdccb9d7;hb=refs%2Fheads%2Fmaster;hp=e8a75d9cf07f4a67c0f50d2c0cc55ea0ca7d88b4;hpb=b3550f16151d5de5b568f06c41c9b29b31a2ffaa;p=cps.git diff --git a/docs/cps-path.rst b/docs/cps-path.rst index e8a75d9cf..eb203d891 100644 --- a/docs/cps-path.rst +++ b/docs/cps-path.rst @@ -1,9 +1,10 @@ .. This work is licensed under a Creative Commons Attribution 4.0 International License. .. http://creativecommons.org/licenses/by/4.0 -.. Copyright (C) 2021-2022 Nordix Foundation +.. Copyright (C) 2021-2023 Nordix Foundation +.. Modifications Copyright (C) 2023 TechMahindra Ltd .. DO NOT CHANGE THIS LABEL FOR RELEASE NOTES - EVEN THOUGH IT GIVES A WARNING -.. _design: +.. _path: CPS Path @@ -176,13 +177,13 @@ General Notes ============= - String values must be wrapped in quotation marks ``"`` (U+0022) or apostrophes ``'`` (U+0027). +- Quotations marks and apostrophes can be escaped by doubling them in their respective quotes, for example ``'CPS ''Path'' Query' -> CPS 'Path' Query`` - String comparisons are case sensitive. -- List key-fields containing ``\`` or ``@[`` will not be processed correctly when being referenced with such key values in absolute or descendant paths. This means such entries will be omitted from any query result. See `CPS-500 `_ Special Character Limitations of cpsPath Queries Query Syntax ============ -``( | ) [ ] [ ] [ ]`` +``( | ) [ ] [ ] [ ] [ ]`` Each CPS path expression need to start with an 'absolute' or 'descendant' xpath. @@ -203,8 +204,6 @@ absolute-path **Limitations** - Absolute paths must start with the top element (data node) as per the model tree. - Each list reference must include a valid instance reference to the key for that list. Except when it is the last element. - - The Absolute path to list with integer key will not work. It needs to be surrounded with a single quote ([@code='1']) - as if it is a string. This will be fixed in `CPS-961 `_ descendant-path --------------- @@ -224,7 +223,7 @@ descendant-path leaf-conditions --------------- -**Syntax**: `` '[' @ '=' ( ' and ' @ '=' )* ']'`` +**Syntax**: `` '[' @ '(=|>|<|>=|<=)' ( ' ' @ '(=|>|<|>=|<=)' )* ']'`` - ``xpath``: Absolute or descendant or xpath to the (list) node which elements will be queried. - ``leaf-name``: The name of the leaf which value needs to be compared. - ``leaf-value``: The required value of the leaf. @@ -234,12 +233,21 @@ leaf-conditions - ``//categories[@name="Kids"]`` - ``//categories[@name='Kids']`` - ``//categories[@code='1']/books/book[@title='Dune' and @price=5]`` - + - ``//categories[@code='1']/books/book[@title='xyz' or @price=15]`` + - ``//categories[@code='1']/books/book[@title='xyz' or @price>20]`` + - ``//categories[@code='1']/books/book[@title='Dune' and @price<=5]`` + - ``//categories[@code=1]`` **Limitations** - Only the last list or container can be queried leaf values. Any ancestor list will have to be referenced by its key name-value pair(s). - - Multiple attributes can only be combined using ``and``. ``or`` and bracketing is not supported. + - When mixing ``and/or`` operators, ``and`` has precedence over ``or`` . So ``and`` operators get evaluated first. + - Bracketing is not supported. + - Leaf names are not validated so ``or`` operations with invalid leaf names will silently be ignored. - Only leaves can be used, leaf-list are not supported. - Only string and integer values are supported, boolean and float values are not supported. + - Using comparative operators with string values will lead to an error at runtime. This error can't be validated earlier as the datatype is unknown until the execution phase. + - The key should be supplied with correct data type for it to be queried from DB. In the last example above the attribute code is of type + Integer so the cps query will not work if the value is passed as string. + e.g.: ``//categories[@code="1"]`` or ``//categories[@code='1']`` will not work because the key attribute code is treated a string. **Notes** - For performance reasons it does not make sense to query using key leaf as attribute. If the key value is known it is better to execute a get request with the complete xpath. @@ -252,7 +260,7 @@ The text()-condition can be added to any CPS path query. **Syntax**: `` ( '/' '[text()=' ']' )?`` - ``cps-path``: Any CPS path query. - ``leaf-name``: The name of the leaf or leaf-list which value needs to be compared. - - ``string-value``: The required value of the leaf or leaf-list element as a string wrapped in quotation marks (U+0022) or apostrophes (U+0027). This wil still match integer values. + - ``string-value``: The required value of the leaf or leaf-list element as a string wrapped in quotation marks (U+0022) or apostrophes (U+0027). This will still match integer values. **Examples** - ``//book/label[text()="classic"]`` @@ -265,6 +273,25 @@ The text()-condition can be added to any CPS path query. - Since CPS cannot return individual leaves it will always return the container with all its leaves. Ancestor-axis can be used to specify a parent higher up the tree. - When querying a leaf value (instead of leaf-list) it is better, more performant to use a text value condition use @ as described above. +contains()-condition +-------------------- + +**Syntax**: `` '[' 'contains' '(' '','' ')' ']'?`` + - ``cps-path``: Any CPS path query. + - ``leaf-name``: The name of the leaf which value needs to be compared. + - ``string-value``: The required value of the leaf element as a string wrapped in quotation marks (U+0022) or apostrophes (U+0027). This will still match integer values. + +**Examples** + - ``//categories[contains(@name,'Sci')]`` + - ``//books[contains(@title,'Space')]`` + +**Limitations** + - Only leaves can be used, leaf-list are not supported. + - Leaf names are not validated so ``contains() condition`` with invalid leaf names will silently be ignored. + +**Notes** + - contains condition is case sensitive. + ancestor-axis -------------