+
+ <section id="pattern-matching">
+ <title> Pattern Matching</title>
+ <para> <literal>*</literal> can be used in a text value and have the usual meaning, so all nodes in the <emphasis>fr</emphasis> can be obtained with:
+ <programlisting>GetNodes ( { 'hostname' : '*.fr' } ) </programlisting>
+ </para>
+ </section>
+
+ <section id="negation">
+ <title> Negation </title>
+ <para> Fields starting with a <literal>~</literal> are negated, so non-local nodes can be fetched with:
+ <programlisting>GetNodes( { '~peer_id' : None } ) </programlisting>
+ </para>
+ </section>
+
+ <section id="numeric">
+ <title> Numeric comparisons </title>
+ <para> Strictly greater/smaller operations are achieved by prepending the field name like in:
+ <programlisting>GetEvents( { '>time' : 1178531418 } ) </programlisting>
+ </para>
+ <para> Greater/smaller or equal:
+ <programlisting>GetEvents( { ']event_id' : 2305 } ) </programlisting>
+ </para>
+ </section>
+
+ <section id="sequence">
+ <title> Filtering on a sequence field </title>
+ <para> A field starting with '&' or '|' should refer to a sequence type;
+ the semantics is then that the object's value (expected to be a list)
+ should contain all (&) or any (|) value specified in the corresponding
+ filter value.
+ <programlisting> GetPersons ( { '|role_ids' : [ 20, 40 ] } ) </programlisting>
+ <programlisting> GetPersons ( { '|roles' : ['tech', 'pi'] } ) </programlisting>
+ <programlisting> GetPersons ( { '&roles' : ['admin', 'tech'] } ) </programlisting>
+ <programlisting> GetPersons ( { '&roles' : 'tech' } ) </programlisting>
+ </para>
+ </section>
+
+ <section id="sort-clip">
+ <title> Sorting and Clipping </title>
+ <para> The following 3 special fields can be used to extract only a subset of the results for pagination:
+ <programlisting> GetNodes( { '-SORT' : 'hostname' , '-OFFSET' : 30 , '-LIMIT' : 25 }</programlisting>
+ </para>
+ </section>
+ </section>
+
+ <section id="and-or">
+ <title> All criteria / Any criteria </title>
+ <para> The default in the vast majority of the code is to select
+ objects that match ALL the criteria specified in the struct. It
+ is possible to search for objects that match ANY of these by
+ adding the special '-OR' key (the value is then ignored), as in:
+ <programlisting> GetPersons ( { '-OR' : 'anything', 'site_id':2, '&roles':['admin'] } ) </programlisting>
+ </para>
+ </section>
+
+ <section id="tags">
+ <title>Tags</title>
+
+ <para> The PLC API comes with a feature called
+ <emphasis>tags</emphasis>, that basically aims at supporting an
+ extensible data model. A few classes (as of this writing, Nodes,
+ Interfaces, Sites, Persons and Slices) are eligible for being dynamically
+ extended beyond the basic set of fields that are built into the
+ database schema.</para>
+
+ <para> Historically, this is a generalization of the concept of
+ <emphasis> SliceAttribute </emphasis>, and the more recent
+ concept of <emphasis> InterfaceSetting </emphasis>, that with
+ release 5.0 have been renamed into <emphasis> SliceTag
+ </emphasis> and <emphasis> InterfaceTag </emphasis>,
+ respectively. </para>
+
+ <section id="tags-low-level">
+ <title> Low level </title>
+ <para> The low level interface to tags relies on the following items: