manuals/getting-started-guide/src/main/asciidoc/ch-xsql-commands.adoc

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