module tailf-netconf-query {

    yang-version 1;

    namespace
      "http://tail-f.com/ns/netconf/query";

    prefix tfncq;

    import tailf-common {
      prefix tailf;
    }
    import tailf-common-query {
      prefix tfcq;
    }

    organization "Tail-f Systems";

    description
      "This module introduces five new rpc operations to run
     advanced search queries.

     The operation 'start-query' starts a query, with some search
     conditions and control parameters for how to return the results.
     This operation returns a query handle, to be used in subsequent
     operations.

     The operation 'fetch-query-result' is repeatedly to get result
     chunks from the query evaluation.

     The operation 'immediate-query' is used to start a new query, and return
     the entire result.

     The operation 'reset-query' can be used to restart the query.

     Finally 'stop-query' is used to clean up query resources on the
     server.

     Copyright 2019 Cisco Systems, Inc.
     All rights reserved.
     Permission is hereby granted to redistribute this file without
     modification.";

    revision "2017-01-06" {
      description
        "Released as part of ConfD-6.5.2.1 / NCS-4.5.3.

       Added 'immediate-query' function.";
    }

    revision "2014-11-13" {
      description "Initial revision.";
    }

    tailf:export "netconf";

    rpc start-query {
      input {
        leaf foreach {
          type yang:xpath1.0;
          mandatory true;
          description
            "An XPath 1.0 expression that returns a node set.  For each
node in this node set, a 'result' entry is constructed.  For
each such node all 'select/expression's are evaluated, and
stored in 'result/select'.  The resulting entries are
returned from the 'fetch-query-result' function.

When this XPath expression is evaluated, the context node is the
root node of the requested data store.";
        }

        list select {
          description
            "A list of expressions that define what to return from each
node in the node set returned by the 'foreach' expression.";
          leaf label {
            type string;
            description
              "Optional label which is copied as is to the 'result' list;
can be used for easy labeling of the returned node(s).";
          }

          leaf expression {
            type yang:xpath1.0;
            mandatory true;
            description
              "Declare what node(s) you want to retrieve.

This XPath expression is evaluated once for every node in
the node set returned by the 'foreach' expression.  That node
is the inital context node when this expression is evaluated.";
          }

          leaf-list result-type {
            type enumeration {
              enum "string" {
                tailf:code-name "result_type_string";
                value 0;
                description
                  "Return the result of evaluating the expression as if it
was surrounded by a call to the xpath function string().";
              }
              enum "path" {
                tailf:code-name "result_type_path";
                value 1;
                description
                  "If the result is a node set, return the path to the
first node in the node set as an instance-identifier.

If the result is not a node set, nothing is returned
for this expression.";
              }
              enum "leaf-value" {
                tailf:code-name "result_type_leaf_value";
                value 2;
                description
                  "If the result is a node set, return the value of the
first node in the node set, if the first node is a leaf.
Otherwise, nothing is returned for this expression.";
              }
              enum "inline" {
                tailf:code-name "result_type_inline";
                value 3;
                description
                  "The result is returned inline, i.e., a deep structure
of XML (or other API dependent format, e.g., JSON)";
              }
            }
            min-elements 1;
            ordered-by user;
            description
              "Controls how the result of the select expression is returned
in 'fetch-query-result'.";
          }
        }  // list select

        leaf-list sort-by {
          type yang:xpath1.0;
          ordered-by user;
          description
            "It is possible to sort the result using an ordered list of
XPath expressions.

For each node in the node set returned by 'foreach', all
'sort-by' expressions are evaluated, in order, with the node
from the 'foreach' evaluation as context node, and the result
is stored in a tuple.  Thus, this tuple has as many elements
as entries in the 'sort-by' leaf list.

Each expression should return a node set where the first
node should be a leaf.  The value of this leaf is used in
the tuple.  If the expression returns something else, the
value in the tuple is undefined.

When the 'result' list is fetched, is is sorted according to
the associated tuple.";
        }

        leaf limit {
          type uint32 {
            range "1..max";
          }
          description
            "The maximum number of 'result' entries to return in each
call to 'fetch-query-result'.

If this parameter is not given, all entries are returned.";
        }

        leaf offset {
          type uint32 {
            range "1..max";
          }
          default "1";
        }

        leaf timeout {
          type uint32 {
            range "1..max";
          }
          default "600";
          description
            "The maximum time (in seconds) before a query times out. Resets every
new request, i.e. subsequent function calls starts a new timeout
timer.";
        }
      }

      output {
        leaf query-handle {
          type uint32;
        }
      }
    }  // rpc start-query

    rpc fetch-query-result {
      input {
        leaf query-handle {
          type uint32;
        }
      }

      output {
        container query-result {
          list result {
            description
              "There will be one result for each node in the node set
produced by evaluating the 'foreach' expression.";
            list select {
              leaf label {
                type string;
                description
                  "Present if the label was given in the input select
entry.";
              }

              choice select-result {
                case path-value {
                  leaf path {
                    type instance-identifier;
                  }

                  leaf value {
                    type string;
                  }
                }  // case path-value
                anyxml data {
                  description
                    "A deep structure of XML (or other API dependent
format, e.g., JSON)";
                }
              }  // choice select-result
            }  // list select
          }  // list result
        }  // container query-result
      }
    }  // rpc fetch-query-result

    rpc immediate-query {
      input {
        leaf foreach {
          type yang:xpath1.0;
          mandatory true;
          description
            "An XPath 1.0 expression that returns a node set.  For each
node in this node set, a 'result' entry is constructed.  For
each such node all 'select/expression's are evaluated, and
stored in 'result/select'.  The resulting entries are
returned from the 'fetch-query-result' function.

When this XPath expression is evaluated, the context node is the
root node of the requested data store.";
        }

        list select {
          description
            "A list of expressions that define what to return from each
node in the node set returned by the 'foreach' expression.";
          leaf label {
            type string;
            description
              "Optional label which is copied as is to the 'result' list;
can be used for easy labeling of the returned node(s).";
          }

          leaf expression {
            type yang:xpath1.0;
            mandatory true;
            description
              "Declare what node(s) you want to retrieve.

This XPath expression is evaluated once for every node in
the node set returned by the 'foreach' expression.  That node
is the inital context node when this expression is evaluated.";
          }

          leaf-list result-type {
            type enumeration {
              enum "string" {
                tailf:code-name "result_type_string";
                value 0;
                description
                  "Return the result of evaluating the expression as if it
was surrounded by a call to the xpath function string().";
              }
              enum "path" {
                tailf:code-name "result_type_path";
                value 1;
                description
                  "If the result is a node set, return the path to the
first node in the node set as an instance-identifier.

If the result is not a node set, nothing is returned
for this expression.";
              }
              enum "leaf-value" {
                tailf:code-name "result_type_leaf_value";
                value 2;
                description
                  "If the result is a node set, return the value of the
first node in the node set, if the first node is a leaf.
Otherwise, nothing is returned for this expression.";
              }
              enum "inline" {
                tailf:code-name "result_type_inline";
                value 3;
                description
                  "The result is returned inline, i.e., a deep structure
of XML (or other API dependent format, e.g., JSON)";
              }
            }
            min-elements 1;
            ordered-by user;
            description
              "Controls how the result of the select expression is returned
in 'fetch-query-result'.";
          }
        }  // list select

        leaf-list sort-by {
          type yang:xpath1.0;
          ordered-by user;
          description
            "It is possible to sort the result using an ordered list of
XPath expressions.

For each node in the node set returned by 'foreach', all
'sort-by' expressions are evaluated, in order, with the node
from the 'foreach' evaluation as context node, and the result
is stored in a tuple.  Thus, this tuple has as many elements
as entries in the 'sort-by' leaf list.

Each expression should return a node set where the first
node should be a leaf.  The value of this leaf is used in
the tuple.  If the expression returns something else, the
value in the tuple is undefined.

When the 'result' list is fetched, is is sorted according to
the associated tuple.";
        }

        leaf limit {
          type uint32 {
            range "1..max";
          }
          description
            "The maximum number of 'result' entries to return in each
call to 'fetch-query-result'.

If this parameter is not given, all entries are returned.";
        }

        leaf offset {
          type uint32 {
            range "1..max";
          }
          default "1";
        }

        leaf timeout {
          type uint32 {
            range "1..max";
          }
          default "600";
          description
            "The maximum time (in seconds) before a query times out. Resets every
new request, i.e. subsequent function calls starts a new timeout
timer.";
        }
      }

      output {
        container query-result {
          list result {
            description
              "There will be one result for each node in the node set
produced by evaluating the 'foreach' expression.";
            list select {
              leaf label {
                type string;
                description
                  "Present if the label was given in the input select
entry.";
              }

              choice select-result {
                case path-value {
                  leaf path {
                    type instance-identifier;
                  }

                  leaf value {
                    type string;
                  }
                }  // case path-value
                anyxml data {
                  description
                    "A deep structure of XML (or other API dependent
format, e.g., JSON)";
                }
              }  // choice select-result
            }  // list select
          }  // list result
        }  // container query-result
      }
    }  // rpc immediate-query

    rpc reset-query {
      input {
        leaf query-handle {
          type uint32;
        }

        leaf offset {
          type uint32 {
            range "1..max";
          }
          default "1";
        }

        leaf timeout {
          type uint32 {
            range "1..max";
          }
          default "600";
          description
            "The maximum time (in seconds) before a query times out. Resets every
new request, i.e. subsequent function calls starts a new timeout
timer.";
        }
      }
    }  // rpc reset-query

    rpc stop-query {
      input {
        leaf query-handle {
          type uint32;
        }
      }
    }  // rpc stop-query
  }  // module tailf-netconf-query