docs/user-guide/running-xsql-console-commands-and-queries.rst

   1 Running XSQL Console Commands and Queries
   2 =========================================
   3
   4 XSQL Overview
   5 -------------
   6
   7 XSQL is an XML-based query language that describes simple stored
   8 procedures which parse XML data, query or update database tables, and
   9 compose XML output. XSQL allows you to query tree models like a
  10 sequential database. For example, you could run a query that lists all
  11 of the ports configured on a particular module and their attributes.
  12
  13 The following sections cover the XSQL installation process, supported
  14 XSQL commands, and the way to structure queries.
  15
  16 Installing XSQL
  17 ---------------
  18
  19 To run commands from the XSQL console, you must first install XSQL on
  20 your system:
  21
  22 1. Navigate to the directory in which you unzipped OpenDaylight
  23
  24 2. Start Karaf:
  25
  26    ::
  27
  28        ./bin/karaf
  29
  30 3. Install XSQL:
  31
  32    ::
  33
  34        feature:install odl-mdsal-xsql
  35
  36 XSQL Console Commands
  37 ---------------------
  38
  39 To enter a command in the XSQL console, structure the command as
  40 follows: **odl:xsql** *<XSQL command>*
  41
  42 The following table describes the commands supported in this
  43 OpenDaylight release.
  44
  45 +-----------------------+----------------------------------------------------+
  46 | **Command**           | **Description**                                    |
  47 +-----------------------+----------------------------------------------------+
  48 | **r**                 | Repeats the last command you executed.             |
  49 +-----------------------+----------------------------------------------------+
  50 | **list vtables**      | Lists the schema node containers that are          |
  51 |                       | currently installed. Whenever an OpenDaylight      |
  52 |                       | module is installed, its YANG model is placed in   |
  53 |                       | the schema context. At that point, the XSQL        |
  54 |                       | receives a notification, confirms that the         |
  55 |                       | module’s YANG model resides in the schema context  |
  56 |                       | and then maps the model to XSQL by setting up the  |
  57 |                       | necessary vtables and vfields. This command is     |
  58 |                       | useful when you need to determine vtable           |
  59 |                       | information for a query.                           |
  60 +-----------------------+----------------------------------------------------+
  61 | **list vfields**      | Lists the vfields present in a specific vtable.    |
  62 | *<vtable name>*       | This command is useful when you need to determine  |
  63 |                       | vfields information for a query.                   |
  64 +-----------------------+----------------------------------------------------+
  65 | **jdbc** *<ip         | When the ODL server is behind a firewall, and the  |
  66 | address>*             | JDBC client cannot connect to the JDBC server, run |
  67 |                       | this command to start the client as a server and   |
  68 |                       | establish a connection.                            |
  69 +-----------------------+----------------------------------------------------+
  70 | **exit**              | Closes the console.                                |
  71 +-----------------------+----------------------------------------------------+
  72 | **tocsv**             | Enables or disables the forwarding of query output |
  73 |                       | as a .csv file.                                    |
  74 +-----------------------+----------------------------------------------------+
  75 | **filename**          | Specifies the .tocsv file to which the query data  |
  76 | *<filename>*          | is exported. If you do not specify a value for     |
  77 |                       | this option when the toccsv option is enabled, the |
  78 |                       | filename for the query data file is generated      |
  79 |                       | automatically.                                     |
  80 +-----------------------+----------------------------------------------------+
  81
  82 Table: Supported XSQL Console Commands
  83
  84 XSQL Queries
  85 ------------
  86
  87 You can run a query to extract information that meets the criteria you
  88 specify using the information provided by the **list vtables** and
  89 **list vfields** *<vtable name>* commands. Any query you run should be
  90 structured as follows:
  91
  92 **select** *<vfields you want to search for, separated by a comma and a
  93 space>* **from** *<vtables you want to search in, separated by a comma
  94 and a space>* **where** *<criteria>* ***\*\ *<criteria operator>****;\*
  95
  96 For example, if you want to search the nodes/node ID field in the
  97 nodes/node-connector table and find every instance of the
  98 Hardware-Address object that contains *BA* in its text string, enter the
  99 following query:
 100
 101 ::
 102
 103     select nodes/node.ID from nodes/node-connector where Hardware-Address like '%BA%';
 104
 105 The following criteria operators are supported:
 106
 107 +----------------+-----------------------------------------------------------+
 108 | **Criteria     | **Description**                                           |
 109 | Operators**    |                                                           |
 110 +----------------+-----------------------------------------------------------+
 111 | **=**          | Lists results that equal the value you specify.           |
 112 +----------------+-----------------------------------------------------------+
 113 | **!=**         | Lists results that do not equal the value you specify.    |
 114 +----------------+-----------------------------------------------------------+
 115 | **like**       | Lists results that contain the substring you specify. For |
 116 |                | example, if you specify **like %BC%**, every string that  |
 117 |                | contains that particular substring is displayed.          |
 118 +----------------+-----------------------------------------------------------+
 119 | **<**          | Lists results that are less than the value you specify.   |
 120 +----------------+-----------------------------------------------------------+
 121 | **>**          | Lists results that are more than the value you specify.   |
 122 +----------------+-----------------------------------------------------------+
 123 | **and**        | Lists results that match both values you specify.         |
 124 +----------------+-----------------------------------------------------------+
 125 | **or**         | Lists results that match either of the two values you     |
 126 |                | specify.                                                  |
 127 +----------------+-----------------------------------------------------------+
 128 | **>=**         | Lists results that are more than or equal to the value    |
 129 |                | you specify.                                              |
 130 +----------------+-----------------------------------------------------------+
 131 | **⇐**          | Lists results that are less than or equal to the value    |
 132 |                | you specify.                                              |
 133 +----------------+-----------------------------------------------------------+
 134 | **is null**    | Lists results for which no value is assigned.             |
 135 +----------------+-----------------------------------------------------------+
 136 | **not null**   | Lists results for which any value is assigned.            |
 137 +----------------+-----------------------------------------------------------+
 138 | **skip**       | Use this operator to list matching results from a child   |
 139 |                | node, even if its parent node does not meet the specified |
 140 |                | criteria. See the following example for more information. |
 141 +----------------+-----------------------------------------------------------+
 142
 143 Table: Supported XSQL Query Criteria Operators
 144
 145 Example: Skip Criteria Operator
 146 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 147
 148 If you are looking at the following structure and want to determine all
 149 of the ports that belong to a YY type module:
 150
 151 -  Network Element 1
 152
 153    -  Module 1, Type XX
 154
 155       -  Module 1.1, Type YY
 156
 157          -  Port 1
 158
 159          -  Port 2
 160
 161    -  Module 2, Type YY
 162
 163       -  Port 1
 164
 165       -  Port 2
 166
 167 If you specify **Module.Type=\ *YY*** in your query criteria, the ports
 168 associated with module 1.1 will not be returned since its parent module
 169 is type XX. Instead, enter **Module.Type=\ *YY* or skip
 170 Module!=\ *YY***. This tells XSQL to disregard any parent module data
 171 that does not meet the type YY criteria and collect results for any
 172 matching child modules. In this example, you are instructing the query
 173 to skip module 1 and collect the relevant data from module 1.1.
 174