X-Git-Url: https://gerrit.onap.org/r/gitweb?a=blobdiff_plain;f=docs%2Fcps-path.rst;h=bc46681d1cb72de953d80ed8c7d99499cdccb9d7;hb=refs%2Fheads%2Fmaster;hp=0271d07e1d42744b49c36ad2028dd8774e418bd1;hpb=0e210d77ec39915046a95615f5f9d2a2dc65162b;p=cps.git
diff --git a/docs/cps-path.rst b/docs/cps-path.rst
index 0271d07e1..eb203d891 100644
--- a/docs/cps-path.rst
+++ b/docs/cps-path.rst
@@ -1,8 +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-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
@@ -19,17 +21,137 @@ The CPS path parameter is used for querying xpaths. CPS path is inspired by the
This section describes the functionality currently supported by CPS Path.
-Sample Data
-===========
+Sample Yang Model
+=================
-The xml below describes some basic data to be used to illustrate the CPS Path functionality.
+.. code-block::
+
+ module stores {
+ yang-version 1.1;
+ namespace "org:onap:ccsdk:sample";
+
+ prefix book-store;
+
+ revision "2020-09-15" {
+ description
+ "Sample Model";
+ }
+ container shops {
+
+ container bookstore {
+
+ leaf bookstore-name {
+ type string;
+ }
+
+ leaf name {
+ type string;
+ }
+
+ list categories {
+
+ key "code";
+
+ leaf code {
+ type uint16;
+ }
+
+ leaf name {
+ type string;
+ }
+
+ leaf numberOfBooks {
+ type uint16;
+ }
+
+ container books {
+
+ list book {
+ key title;
+
+ leaf title {
+ type string;
+ }
+ leaf price {
+ type uint16;
+ }
+ leaf-list label {
+ type string;
+ }
+ leaf-list edition {
+ type string;
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+
+**Note.** 'categories' is a Yang List and 'code' is its key leaf. All other data nodes are Yang Containers. 'label' and 'edition' are both leaf-lists.
+
+**Note.** CPS accepts only json data. The xml data presented here is for illustration purposes only.
+
+The json and xml below describes some basic data to be used to illustrate the CPS Path functionality.
+
+Sample Data in Json
+===================
+
+.. code-block:: json
+
+ {
+ "shops": {
+ "bookstore": {
+ "bookstore-name": "Chapters",
+ "name": "Chapters",
+ "categories": [
+ {
+ "code": 1,
+ "name": "SciFi",
+ "numberOfBooks": 2,
+ "books": {
+ "book": [
+ {
+ "title": "2001: A Space Odyssey",
+ "price": 5,
+ "label": ["sale", "classic"],
+ "edition": ["1968", "2018"]
+ },
+ {
+ "title": "Dune",
+ "price": 5,
+ "label": ["classic"],
+ "edition": ["1965"]
+ }
+ ]
+ }
+ },
+ {
+ "code": 2,
+ "name": "Kids",
+ "numberOfBooks": 1,
+ "books": {
+ "book": [
+ {
+ "title": "Matilda"
+ }
+ ]
+ }
+ }
+ ]
+ }
+ }
+ }
+
+Sample Data in XML
+==================
.. code-block:: xml
Chapters
-
+
@@ -43,7 +165,7 @@ The xml below describes some basic data to be used to illustrate the CPS Path fu
-
+
@@ -51,19 +173,17 @@ The xml below describes some basic data to be used to illustrate the CPS Path fu
-**Note.** 'categories' is a Yang List and 'code' is its key leaf. All other data nodes are Yang Containers. 'label' and 'edition' are both leaf-lists.
-
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.
@@ -78,8 +198,8 @@ absolute-path
**Examples**
- ``/shops/bookstore``
- - ``/shops/bookstore/categories[@code=1]``
- - ``/shops/bookstore/categories[@code=1]/book``
+ - ``/shops/bookstore/categories[@code='1']/books``
+ - ``/shops/bookstore/categories[@code='1']/books/book[@title='2001: A Space Odyssey']``
**Limitations**
- Absolute paths must start with the top element (data node) as per the model tree.
@@ -94,7 +214,7 @@ descendant-path
**Examples**
- ``//bookstore``
- - ``//categories[@code=1]/book``
+ - ``//categories[@code='1']/books``
- ``//bookstore/categories``
**Limitations**
@@ -103,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.
@@ -112,13 +232,22 @@ leaf-conditions
- ``/shops/bookstore/categories[@numberOfBooks=1]``
- ``//categories[@name="Kids"]``
- ``//categories[@name='Kids']``
- - ``//categories[@code=1]/book[@title='Dune' and price=5]``
-
+ - ``//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.
@@ -131,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"]``
@@ -144,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
-------------
@@ -155,9 +303,9 @@ The ancestor axis can be added to any CPS path query but has to be the last part
**Examples**
- ``//book/ancestor::categories``
- - ``//categories[@genre="SciFi"]/book/ancestor::bookstore``
- - ``book/ancestor::categories[@code=1]/books``
- - ``//book/label[text()="classic"]/ancestor::shop``
+ - ``//categories[@code='2']/books/ancestor::bookstore``
+ - ``//book/ancestor::categories[@code='1']/books``
+ - ``//book/label[text()="classic"]/ancestor::shops``
**Limitations**
- Ancestor list elements can only be addressed using the list key leaf.