module yumaworks-getbulk {

    yang-version 1;

    namespace
      "http://yumaworks.com/ns/yumaworks-getbulk";

    prefix ybulk;

    import ietf-yang-types {
      prefix yang;
    }
    import ietf-netconf-with-defaults {
      prefix wd;
    }
    import yumaworks-restconf {
      prefix yrc;
    }

    organization "YumaWorks, Inc.";

    contact
      "Support <support at yumaworks.com>";

    description
      "Get bulk retrieval

       The <get-bulk> RPC operation provides controlled iteration
       procedure over instances of a YANG list object.

     Copyright (c) 2016 - 2021, YumaWorks, Inc. All rights reserved.

     Redistribution and use in source and binary forms, with or
     without modification, is permitted pursuant to, and subject
     to the license terms contained in, the BSD 3-Clause License
     http://opensource.org/licenses/BSD-3-Clause.

      +---x get-bulk
          +---w input
          |  +---w datastore?       enumeration
          |  +---w list-target      string
          |  +---w count?           uint32
          |  +---w depth?           union
          |  +---w with-defaults?   with-defaults-mode
          |  +---w last-keys
          |  +---w list-test        yang:xpath1.0
          |  +---w fixed-keys
          +--ro output
             +--ro bulk
                 +--ro data
                 +--ro last-keys

        Example Module

          container top {
            list A {
              key 'k1 k2';
              leaf k1 { type int32; }
              leaf k2 { type string; }
              list B {
                key k3;
                leaf k3 { type int32; }
                leaf c1 { type int32; }
              }
            }
          }

       Basic Operation

         Iterate over B within A entry '42, foo'

       First request:

        <get-bulk>
          <list-target>/top/A=42,foo/B</list-target>
          <count>3</count>
        </get-bulk>

       First reply: 3 instances of B are returned

        <bulk>
          <last-keys>
            <k3>3</k3>
          </last-keys>
          <data>
            <B>
              <k3>1</k3>
              <c1>100</c1>
            </B>
            <B>
              <k3>2</k3>
              <c1>87</c1>
            </B>
            <B>
              <k3>3</k3>
              <c1>16</c1>
            </B>
          </data>
        </bulk>

       Second request:

        <get-bulk>
          <list-target>/top/A=42,foo/B</list-target>
          <count>3</count>
          <last-keys>
            <k3>3</k3>
          </last-keys>
        </get-bulk>
    ";

    revision "2021-08-07" {
      description
        "Add fixed-keys parameter to get-bulk operation";
    }

    revision "2020-10-02" {
      description
        "Clarify XPath usage for list-test parameter";
    }

    revision "2018-04-06" {
      description "Add list-test parameter";
    }

    revision "2016-05-10" {
      description "Initial version";
    }


    rpc get-bulk {
      description
        "Retrieve multiple list entries at a time";
      input {
        leaf datastore {
          type enumeration {
            enum "candidate" {
              value 0;
            }
            enum "running" {
              value 1;
            }
            enum "startup" {
              value 2;
            }
          }
          default "running";
          description
            "Identifies the datastore source for the retrieval,
             if the list-object is a configuration data node.
             If not a configuration node, then this object
             will be ignored if present.";
        }

        leaf list-target {
          type string;
          mandatory true;
          description
            "Identifies the list object that is being retrieved.
             This must be a path expression used to represent
             a list data node.  It is formated like a RESTCONF
             path expression, except module names are not mandatory
             if they are unique.";
        }

        leaf count {
          type uint32 {
            range "1 .. max";
          }
          default '1';
          description
            "The maximum number of list entries to return.";
        }

        uses yrc:content-parameter {
          description
            "The content parameter is used as defined in the
             RESTCONF protocol. This parameter will be ignored
             if the list-target is a nonconfig node. In that case
             only nonconfig data nodes will be returned.";
          refine content {
            default 'all';
          }
        }

        uses yrc:depth-parameter {
          description
            "The depth parameter is used as defined in the
             RESTCONF protocol. The value '1' is associated
             with the list-object node itself.  This value
             can be used to simply test for the existence
             of any instances of the list-object.";
        }

        uses wd:with-defaults-parameters {
          description
            "The with-defaults parameter is used as defined in the
             NETCONF protocol.";
        }

        anyxml last-keys {
          description
            "Represents all the keys for the last instance
             of the list-object that was previously retrieved.
             If empty or missing, then the get-bulk will start
             with the first instance of the list-object.
             Otherwise, all key leafs for the list-object must
             be specified in the order of the key statement
             for the list-object.";
        }

        leaf list-test {
          type yang:xpath1.0;
          description
            "Specifies an XPath boolean expression that will
             be used to determine if a list entry specified
             by the list target should be included in the
             response.

             The document root and the context node for the
             XPath evaluation will be each list-target instance.
             If the list-test expression is invalid, then an
             error will be returned. If the expression evaluates
             successfully then the function boolean(result)
             will be used to determine if the list instance
             should be included in the response.

             For example, if the list-target is /interfaces/interface
             then the expression type = 'ethernetCsmacd' will select
             only interface entries with the specified type leaf value.

             The XPath expression must be use relative path expressions
             since the list-target instance is the document root, and
             no 'parent' node will exist for this instance.

             For configuration and virtual operational nodes
             (GET1 callback) any XPath expression is allowed
             for this object. The entire subtree starting with
             the list-target instance will be accessible for
             the XPath expression evaluation.

             For most operational nodes (GET2 callback) the XPath
             expression is constrained for this object. Only the
             terminal nodes that are children of the list-target
             instance will be accessible for the XPath expression
             evaluation.
            ";
        }

        anyxml fixed-keys {
          description
            "Represents any keys that should be fixed in value.
             If empty or missing, then the get-bulk will scan all
             values of a key leaf. If present then the get-bulk
             response will only include values that have a matching
             value for the key leaf.";
        }
      }

      output {
        container bulk {
          anyxml data {
            description
              "Contains the list entries that were requested.
               Will be empty if there were no matching entries";
          }

          anyxml last-keys {
            description
              "Represents all the keys for the last instance
               of the list-object that is being returned in the
               response. The returned subtree can be used in the
               next get-bulk request as the 'last-keys' parameter.";
          }
        }  // container bulk
      }
    }  // rpc get-bulk
  }  // module yumaworks-getbulk