Query Builder field reference
You can use the Query Builder to enter rules for the automatic selection of VMware virtual machines for backup.
Note:
You can configure and manage VMware policies with the NetBackup web UI. In the web UI, the advanced mode of the Query Builder uses OData keywords and operators. Otherwise, the Query Builder functions the same way as in the NetBackup Administration Console.
Table: Query Builder drop-down options: Join, Field, Operator, Value(s) describes the drop-down fields and options for creating rules in the Query Builder.
Table: Query Builder drop-down options: Join, Field, Operator, Value(s)
Query Builder drop-down fields | Description |
|---|---|
Join | Selects a connector to join rules. For the first rule, choices are blank (none) or NOT. After you add a rule, the available connectors are AND, AND NOT, OR, OR NOT. |
Field | Selects a parameter on which to build the rule. Select one from the list (scroll down for additional parameters). You can type the first character to speed up selection. For example, on entering "d", the list moves to first entry starting with "d". Another entry of "d" moves through the list to the next entry starting with "d". The selected entry is automatically filled in. |
Operator | Selects an operator. The available operators depend on the parameter that is selected for Field. |
Value(s) | Specifies a value for the Field parameter. The Value field allows manual entry. It may also be a drop-down, depending on the selections that are made in the other fields. For manual entry, you can specify multiple comma-separated values. |
Allows browsing for specific values, depending on the selections that are made in the other drop-down fields. | |
Adds the current drop-down selections to the Query pane as a new rule. | |
Blanks out the drop-down fields. |
Field (keywords)
Table: Keywords in the Field drop-down describes the keywords available in the Field drop-down. The table also indicates whether the values for each keyword (in the Values field) are case-sensitive.
Note:
Use OData Field keywords only when you build queries with the NetBackup web UI 's advanced mode under the Query Builder or with NetBackup APIs.
Keep in mind that the inclusion or exclusion of virtual machines is not determined by the Field keyword alone, but depends on the rule you construct: the combination of Join, Field, Operator, and Values.
Table: Keywords in the Field drop-down
Field keyword | OData field keyword | Data type | Description |
|---|---|---|---|
Annotation | annotation | Alphanumeric string | The text that is added to virtual machine annotations in vSphere Client. Values are case-sensitive. |
AssetGroup | assetGroup | NEW | |
Cluster | cluster | Alphanumeric string | The name of the cluster (a group of ESX servers) that the virtual machine is configured in. Values are not case-sensitive. Note: A virtual machine may be assigned to an ESX server that is not in a cluster. Note also that in VMware, a cluster name need only be unique within a datacenter path. |
Datacenter | datacenter | Alphanumeric string | The name of the VMware datacenter. Values are not case-sensitive. |
DatacenterPath | datacenterPath | Alphanumeric string | The folder structure that defines the path to a datacenter. Use this option if the datacenter name that you want to filter on is not unique in your environment. Values are case-sensitive. |
Datastore | datastoreName | Alphanumeric string | The name of the datastore. Values are case-sensitive. Note: Multiple ESX servers can share access to the same datastore. Also, a datastore name can be duplicated between multiple ESX servers. Use DatacenterPath or ESXserver to uniquely identify the datacenter. |
DatastoreCluster | datastoreCluster | Alphanumeric string | The name of the datastore cluster that contains the datastores. Values are not case-sensitive. |
DatastoreFolder | datastoreFolder | Alphanumeric string | The name of the folder that contains the datastores. Values are not case-sensitive. |
DatastoreNFSHost | datastoreNfsHost | Alphanumeric string | The name of the datastore's NFS host. Values are not case-sensitive. |
DatastoreNFSPath | datastoreNfsPath | Alphanumeric string | The folder structure that defines the path to an NFS datastore. Use this option if the NFS host name of the datastore that you want to filter on is not unique in your environment. Values are not case-sensitive. |
DatastoreType | datastoreType | Alphanumeric string | The type of the datastore. Values are NFS, NFS41, VMFS, vsan, and VVOL. Values are not case-sensitive. |
Displayname | displayName | Alphanumeric string | The virtual machine's display name. Values are case-sensitive. |
ESXserver | host | Alphanumeric string | The name of the ESX server. Values are not case-sensitive. The ESX host name must match the name as defined in the vCenter server. |
HostFolder | hostFolder | Alphanumeric string | The folder path between the datacenter level and a cluster, ESX hosts, or a subfolder. If an ESX cluster is not contained within a folder and you click the browse for values button, note: The ESX cluster name appears in the Select From List dialog. Values are not case-sensitive. |
InstanceUUID | instanceUuid | Alphanumeric string | The virtual machine's instance UUID. Example query: InstanceUUID Equal "501b13c3-52de-9a06-cd9a-ecb25aa975d1" Values are not case-sensitive. |
Network | network | Alphanumeric string | The name of the network switch (on an ESX server) or distributed switch. Values are not case-sensitive. |
NetworkFolder | networkFolder | Alphanumeric string | The name of the folder that contains the network. Values are not case-sensitive. |
Powerstate | powerState | Alphabetic | The power state of the virtual machine. Values are poweredOff, poweredOn, suspended. |
Resourcepool | resourcePool | Alphanumeric string | The name of the resource pool. (A resource pool is similar to a vApp.) Values are case-sensitive. If a resource pool contains other resource pools (sub-pools), the choice of Operator determines whether virtual machines in the sub-pools are included. |
Tag | tagName | Alphanumeric string | The name of the tag. Values are case-sensitive. When NetBackup uses tags to select virtual machines, the selection is based only on tag names. The selection is independent of the category. See Query rules for tags. |
Template | template | Boolean | TRUE if the virtual machine is a virtual machine template. |
vApp | vApp | Alphanumeric string | The name of the vApp. Values are case-sensitive. A vApp is a collection of virtual machines. vApps can also contain resource pools and other vApps. vApps are components of standalone ESX servers or of clusters. Like vSphere Client, NetBackup refers only to the top level of a vApp that contains sub vApps. For the following rule: vApp Equal "vapp1" if vapp1 has a sub vApp named "vapp2", any virtual machines in vapp1 or vapp2 are included. You cannot make a rule that refers specifically to vapp2. |
vCDCatalog | vcdCatalog | Alphanumeric string | The name of the vCloud Director catalog. Values are not case-sensitive. |
vCDIsExpired | vcdIsExpired | Alphabetic | Expired if the vCloud Director vApp or vApp template is expired. Possible values are Expired, Not Expired, and Unknown. Unknown indicates that an error occurred between vCloud Director and the vSphere environment. Examples are errors in provisioning or in a deletion operation. |
vCDIsvAppTemplate | vcdIsvAppTemplate | Boolean | TRUE if the vCloud Director vApp is a template. |
vCDOrg | vcdOrg | Alphanumeric string | The name of the vCloud Director organization. Values are not case-sensitive. |
vCDOrgvDC | vcdOrgvDC | Alphanumeric string | The name of the organization virtual datacenter in vCloud Director. Values are not case-sensitive. |
vCDServer | vcdServer | Alphanumeric string | The name of the vCloud Director server. Values are not case-sensitive. |
vCDvApp | vcdVapp | Alphanumeric string | The name of the vCloud Director vApp. Values are not case-sensitive. |
vCenter | vCenter | Alphanumeric string | The name of the vCenter server. Values are not case-sensitive. The vCenter name that is specified in the Query Builder must match the name as entered in the Administration Console for NetBackup credentials. (Media and Device Management > Credentials > Virtual Machine Servers.) Note that a fully qualified domain name is recommended. |
vCenterVersion | vCenterVersion | Alphanumeric string | The version of the vCenter Server. For example: 5.1.0, 5.5.0, 6.0.0 The possible values of this field are automatically updated and populated based on the environment. Only the versions of the vCenter servers that are registered with NetBackup are shown. |
VMDNSName | dnsName | Alphanumeric string | The virtual machine DNS name in vSphere Client. Values are not case-sensitive. |
VMFolder | vmFolder | Alphanumeric string | The name of the VM folder (within a datacenter), including the path to the folder that contains the VMs. Values are not case-sensitive. For example, assume the following VM folders containing a total of 65 VMs: vm\VM_backup_prod1 (contains 5 VMs) vm\VM_backup_prod1\cluster1 (contains 10 VMs) vm\VM_backup_prod2 (contains 50 VMs) To include the VMs in VMFolder Equal "vm\VM_backup_prod1" To include the VMs in VMFolder Equal "vm\VM_backup_prod1" OR VMFolder StartsWith "vm\VM_backup_prod1\\" Note: The first backslash is an escape character that causes the following backslash to be interpreted as a literal character. To include all 65 VMs: VMFolder StartsWith "vm\VM_backup_prod" Note: Any VM that is in a path that begins with |
VMGuestOS | vmGuestOs | Alphanumeric string | The virtual machine guest OS type that is recorded in vSphere Client. Values are case-sensitive. |
VMHasIDE | vmHasIde | Boolean | TRUE if the virtual machine has IDE drives. |
VMhasIndD | vmHasIndD | NEW | |
VMHasMDS | vmHasMds | Boolean | TRUE if the virtual machine has multiple datastores. You can use this keyword to select any virtual machine that is configured to use more than one datastore. |
VMHasNVME | vmHasNvme | Boolean | TRUE if the virtual machine has NVMe drives. |
VMHasRDM | vmHasRdm | Boolean | TRUE if the virtual machine uses Raw Device Mapping (RDM). |
VMHasRDMO | vmHasRdmo | NEW | |
VMHasSATA | vmHasSata | Boolean | TRUE if the virtual machine has SATA drives. |
VMHasSnap | VMHasSnap | Boolean | TRUE if a VMware snapshot of the virtual machine is currently active. |
VMHasVDSName | vmHasVdsName | Boolean | TRUE if the virtual machine has a display name that is valid for use as the host name. |
VMHostName | hostName | Alphanumeric string | The virtual machine name that is derived from a reverse lookup of its IP address. Values are not case-sensitive. |
VMIsConn | vmIsConn | Boolean | TRUE if the virtual machine is connected and available. For example: If a virtual machine's ESX server is down, that virtual machine is not connected. |
VMVersion | vmVersion | Alphanumeric string | The VMware version of the virtual machine. Values are case-sensitive. For example: vmx-04, vmx-07, vmx-08. |
VMXDatastore | vmxDatastore | Alphanumeric string | The name of the vmx datastore (sometimes called the vmx directory or configuration datastore). Values are case-sensitive. More information on the vmx datastore is available. |
VMXDatastoreFolder | vmxDatastoreFolder | Alphanumeric string | The name of the folder that contains the vmx datastores. Values are not case-sensitive. |
VMXDatastoreNFSHost | vmxDatastoreNfsHost | Alphanumeric string | The name of the vmx datastore's NFS host. Values are not case-sensitive. |
VMXDatastoreNFSPath | vmxDatastoreNfsPath | Alphanumeric string | The folder structure that defines the path to a vmx NFS datastore. Use this option if the NFS host name of the datastore that you want to filter on is not unique in your environment. Values are not case-sensitive. |
VMXDatastoreType | vmxDatastoreType | Alphanumeric string | The type of the vmx datastore. Values are NFS or VMFS. Values are not case-sensitive. |
[vSphere custom attributes] | [vSphere custom attributes] | Alphanumeric string | The value of a custom attribute that is set in vSphere Client for one or more virtual machines. Note: in vSphere Client, the attribute must have a value for at least one virtual machine. The attribute type must be Virtual Machine. The values are case-sensitive. Custom Attribute based disk exclusion requires that you enter in NetBackup the credentials for the vCenter server or servers that host the VMs. ESXi server credentials are not sufficient. |
Operators
Table: Operators in the Operator drop-down describes the operators available in the Operator drop-down. Note that in some cases, the operator is that is used in the NetBackup Administration Console is different from the operator that is used in the NetBackup web UI.
Note:
Use OData operators only when you build queries with the NetBackup web UI's advanced mode under the Query Builder or with NetBackup APIs.
Table: Operators in the Operator drop-down
Operator | OData operator | Description |
|---|---|---|
AnyOf (NetBackup Administration Console) In (NetBackup web UI) | in | Matches any of the specified values in the Value(s) field. For example: If the ESX servers in the Value(s) field are "ESX01","ESX02,"ESX03", AnyOf matches any ESX server that has one of those names. If the names of your servers are not identical to any of the specified values, no match occurs. A server named ESX01A is not a match. |
Contains | contains | Matches the value in the Value(s) field wherever that value occurs in the string. For example: If the Value(s) entry is "dev", Contains matches strings such as "01dev", "01dev99", "devOP", and "Development_machine". |
EndsWith | endswith | Matches the value in the Value(s) field when it occurs at the end of a string. For example: If the Value(s) entry is "dev", EndsWith matches the string "01dev" but not "01dev99", "devOP", or "Development_machine". |
Equal | eq | Matches only the value that is specified in the Value(s) field. For example: If the display name to search for is "VMtest27", Equal matches virtual machine names such as VMTest27 or vmtest27 or vmTEST27, and so forth. The name VMtest28 is not matched. |
Greater | gt | Matches any value that is greater than the specified Value(s), according to the UTF-8 collating sequence. |
GreaterEqual | ge | Matches any value that is greater than or equal to the specified Value(s), according to the UTF-8 collating sequence. |
IsSet (NetBackup Administration Console) NotEqual nullIn (NetBackup web UI) | ne null | Determines whether a value is returned for the Field keyword. Use IsSet with another rule as a condition, to ensure that the query selects the appropriate virtual machines. Note that you do not make an entry under Value(s) for a rule that uses IsSet. See The IsSet operator in queries. See Effect of Primary VM identifier parameter on Selection column in Test Query results. |
Less | lt | Matches any value that is less than the specified Value(s), according to the UTF-8 collating sequence. |
LessEqual | le | Matches any value that is less than or equal to the specified Value(s), according to the UTF-8 collating sequence. |
NotEqual | ne | Matches any value that is not equal to the value in the Value(s) field. |
StartsWith | startswith | Matches the value in the Value(s) field when it occurs at the start of a string. For example: If the Value(s) entry is "box", StartsWith matches the string "box_car" but not "flatbox". |
Value(s)
Table: Characters you can enter for Value(s) describes the characters that can be entered in the Value(s) field. The Field keyword determines case sensitivity.
Note:
The character string you enter in the Value(s) field must be enclosed in single quotes or double quotes.
Table: Characters you can enter for Value(s)
Character types | String characters allowed |
|---|---|
Alphanumerics | A to Z, a to z, 0 to 9, - (minus sign), and special characters. Note: Decimal numbers only. |
Wildcards | * (asterisk) matches everything. For example: "*prod*" matches the string "prod" preceded or followed by any characters. ? (question mark) matches any single character. For example: "prod??" matches the string "prod" followed by any two characters. |
Escape character | \ (backslash) escapes the wildcard or meta-character that follows it. For example: To search for a string that contains an asterisk (such as test*), enter "test\*" |
Quotation marks | Note: The characters you enter in Value(s) must be enclosed in single or double quotes. To search for a string that contains quotation marks, either escape each quote (\") or enclose the entire string in the opposite type of quotes. For example: To search for a string that includes double quotes (such as "name"), enter '"name"' (enclosing it in single quotes) or "\"name\"" |