ZStack Cloud 4.4.0>Product Manuals>zstack-cli Command Manual>Query

Query

Overview

ZStack Cloud provides comprehensive APIs to query every field of every resource.

Architecture

Every resource in ZStack Cloud groups its properties as an inventory in JSON format.

The following is an example of a zone inventory:

{
            "createDate": "Nov 17, 2017 8:27:47 PM",
            "description": "Test",
            "lastOpDate": "Nov 20, 2017 5:40:52 PM",
            "name": "Zone-1",
            "state": "Enabled",
            "type": "zstack",
            "uuid": "c3a228078e8c4f81ba7da0b16fb8d77f"
        }

A resource inventory can include inventories of other resources. For example, an L3 network inventory includes an IP range inventory.

{
            "category": "Public",
            "createDate": "Nov 17, 2017 9:11:59 PM",
            "dns": [
                "223.5.5.5"
            ],
            "ipRanges": [
                {
                    "createDate": "Nov 17, 2017 9:18:47 PM",
                    "endIp": "10.108.10.110",
                    "gateway": "10.0.0.1",
                    "l3NetworkUuid": "a8b7054aaa9141f696afebdb1721e5c8",
                    "lastOpDate": "Nov 17, 2017 9:18:47 PM",
                    "name": "L3-Pub",
                    "netmask": "255.0.0.0",
                    "networkCidr": "10.0.0.1/8",
                    "startIp": "10.108.10.100",
                    "uuid": "df5b1ab49a53440bb44eb14c7ebfd50a"
                }
            ],
            "l2NetworkUuid": "16fecf5ff5754c3fb6669986ec1fe645",
            "lastOpDate": "Nov 17, 2017 9:11:59 PM",
            "name": "L3-Pub",
            "networkServices": [
                {
                    "l3NetworkUuid": "a8b7054aaa9141f696afebdb1721e5c8",
                    "networkServiceProviderUuid": "3d46e334773845adac0d90c86a5999ee",
                    "networkServiceType": "Userdata"
                },
                {
                    "l3NetworkUuid": "a8b7054aaa9141f696afebdb1721e5c8",
                    "networkServiceProviderUuid": "3d46e334773845adac0d90c86a5999ee",
                    "networkServiceType": "Eip"
                },
                {
                    "l3NetworkUuid": "a8b7054aaa9141f696afebdb1721e5c8",
                    "networkServiceProviderUuid": "3d46e334773845adac0d90c86a5999ee",
                    "networkServiceType": "DHCP"
                }
            ],
            "state": "Enabled",
            "system": false,
            "type": "L3BasicNetwork",
            "uuid": "a8b7054aaa9141f696afebdb1721e5c8",
            "zoneUuid": "c3a228078e8c4f81ba7da0b16fb8d77f"
        }

An inventory has two types of fields: primitive field and nested field.

A primitive field consists of primitive types, such as number, string, boolean, and date. In the example above, uuid, name, and system are primitive fields.
A nested field includes other types except for the primitive types. In the example above, ipRanges is a nested field.

Note:

Unless explicitly stated, every field of every inventory can be queried.
Every inventory has its corresponding query API, such as QueryZone, QueryHost, and QueryVmInstance.
The response of a query API always carries a list of inventories, or an empty list if no matching result is found.

The following is an example of a query response:

{
    "inventories": [
        {
            "allocatorStrategy": "LeastVmPreferredHostAllocatorStrategy",
            "cpuNum": 1,
            "cpuSpeed": 0,
            "createDate": "Nov 17, 2017 8:48:06 PM",
            "lastOpDate": "Nov 17, 2017 8:48:06 PM",
            "memorySize": 1073741824,
            "name": "instance-offering",
            "sortKey": 0,
            "state": "Enabled",
            "type": "UserVm",
            "uuid": "32c3405f7bbf43009cfaf58cb41e39fc"
        }
    ],
    "success": true
}

A query API consists of a list of query conditions and several helper parameters.

Parameters

Name	Description	Optional	Valid Value	Starting Version
conditions	A list of :ref:`QueryCondition <QueryCondition>`.			0.6
limit	The maximum number of inventories that can be returned by the query API. Default value: 1000.	true		0.6
start	The first inventory to return. Default value: 0.	true		0.6
count	If true, the query response only returns the inventory count. Default value: false.		true false	0.6
replyWithCount	If true, the query response returns both the inventories and the inventory count. Default value: false.		true false	0.6
sortBy	The field by which the result inventories will be sorted. This field must be a primitive field.	true		0.6
sortDirection	If sortBy is not null, this parameter specifies the sort direction. Default value: asc.		asc desc	0.6
fields	A list of primitive fields. If specified, only these primitive fields will be included in the query response.	true		0.6

Query Condition

Query APIs receive a list of query conditions. Properties included in the query conditions are as follows.

Name	Description	Valid Value	Starting Version
name	The field name.		0.6
op	The comparison operator.	= != > >= < <= in not in is null is not null like not like	0.6
value	The query value.		0.6

The field name can be a primitive field name, a sub-field name of a nested field, or a sub-field name of an expanded field. (See :ref:Join <query join>). op is a comparison operator in SQL.

Operator	CLI Form	Description
=	=	The equal operator. The string comparison is case-sensitive.
!=	!=	The not equal operator. The string comparison is case-sensitive.
>	>	The greater than operator. For information about the string comparison, see Operators in MySQL Reference Manual.
>=	>=	The greater than or equal operator. For information about the string comparison, see Operators in MySQL Reference Manual.
<	<	The less than operator. For information about the string comparison, see Operators in MySQL Reference Manual.
<=	<=	The less than or equal operator. For information about the string comparison, see Operators in MySQL Reference Manual.
in	?=	Checks whether a value is within a set of values.
not in	!?=	Checks whether a value is NOT within a set of values.
is null	=null	Checks whether a value is NULL.
is not null	!=null	Checks whether a value is not NULL.
like	~=	Simple pattern matching. Use % to match any number of characters, even zero characters. Use _ to match exactly one character.
not like	!~=	Negation of simple pattern matching. Use % to match any number of characters, even zero characters. Use _ to match exactly one character.

The relationship between query conditions is logical AND, which is the only relationship supported currently. For example,

# Query the L3 network with the name of L3Network1 and one or more IP range named range1.
QueryL3Network ipRanges.name=range1 name=L3Network1

Query Conditions in zstack-cli

Two methods of using query conditions are available in zstack-cli.

Original form of query API:

QueryHost conditions='[{"name":"name", "op":"=", "value":"KVM1"}]'

zstack-cli form:
```
QueryHost name=KVM1
```

Obviously, the zstack-cli form is more intuitive and readable. The following zstack-cli form is usually used to express query conditions:

condition_name(no_space)CLI_comparison_operator(no_space)condition_value

When you type a command in zstack-cli, you can use the Tab key for automatic completion or reminding you of the queryable fields, including primitive fields, nested fields, and expanded fields.

admin >>>QueryVmInstance
[Query Conditions:]
allVolumes.            cluster.               host.                  image.                 instanceOffering.
resourcePool.          rootVolume.            vmCdRoms.              vmNics.                zone.


__systemTag__=         __tagUuid__=           __userTag__=           allocatorStrategy=     clusterUuid=
cpuNum=                cpuSpeed=              createDate=            defaultL3NetworkUuid=  description=
groupBy=               hostUuid=              hypervisorType=        imageUuid=             instanceOfferingUuid=
lastHostUuid=          lastOpDate=            memorySize=            name=                  platform=
rootVolumeUuid=        state=                 systemTags=            type=                  userTags=
uuid=                  zoneUuid=

[Parameters:]
count=                 fields=                limit=                 replyWithCount=        sortBy=
sortDirection=         start=                 timeout=

Join (Expanded Query)

In ZStack Cloud, Join is called expanded query. This kind of query allows you to query a resource by fields that have relation to this resource. In ZStack Cloud, these fields are called expanded fields.

For example, you can query an L3 network according to the VIP 10.108.10.102, which is the EIP of a VM NIC.

admin >>>QueryL3Network vmNic.eip.vipIp=10.108.10.102

In the example above, the L3 network inventory does not have the vmNic.eip.vipIp field. However, this IP address has a relation to the VM NIC inventory. Meanwhile, the VM NIC inventory has a relation to the EIP inventory. Therefore, you can construct an expanded query across three inventories, including the L3 network inventory, the VM NIC inventory, and the EIP inventory.

Based on the Join (expanded query) condition, ZStack Cloud can provide nearly 4 million query conditions and countless combinations of conditions.

The following is a complex example to show the strong query function:

QueryVolumeSnapshot volume.vmInstance.vmNics.l3Network.l2Network.attachedClusterUuids?=13238c8e0591444e9160df4d3636be82

The example above is to query volume snapshots that were created from volumes of VM instances. The VM instances have NICs on L3 networks whose parent L2 networks are attached to a cluster with the UUID of 13238c8e0591444e9160df4d3636be82.

Query List

When a field is a list, it can contain primitive types such as int, long, string, and nested inventories.

Query list is not special. This section is to remind you that do not think you can only use in (?=) and not in (!?=) to query a list. In fact, you can use all comparison operators.

For example,

# To query all L3 networks with the similar DNS 72.72.72.* 
QueryL3Network dns~=72.72.72.%

# To query all L3 networks with the IP range starting from 192.168.0.10
QueryL3Network ipRanges.startIp=192.168.0.10

Query Tags

In this section, you can see that every resource have system tags and user tags. Both the system tags and user tags can be a part of query conditions.

ZStack Cloud uses two special fields (__userTag__ and __systemTag__) to query resources.

For example,

QueryVmInstance __userTag__?=web-tier-VMs

QueryHost __systemTag__?=os::distribution::Ubuntu managementIp=192.168.0.212

Operators, such as >, >=, < and <=, only return resources with tags that match specified conditions.
is not null returns all resources that have tags.
is null returns all resources that have no tags.
!=, not in, and not like return resources with tags that do not match conditions and resources that have no tags.

Avoid Loop Query

Most ZStack Cloud resources support bidirectional expanded query.

For example, a host query can be expanded to a cluster to which the host belongs, and a cluster query can also be expanded to a host in the cluster. This makes it possible to query resources in any direction, which might also lead to loop query at the same time.

For example,

QueryHost vmInstance.vmNics.eip.vmNic.vmInstance.uuid=d40e459b97db5a63dedaffcd05cfe3c2

The example above is a loop query and does the same thing as the following query example does:

QueryHost vmInstance.uuid=d40e459b97db5a63dedaffcd05cfe3c2

The behavior of a loop query is undefined. You may or may not get the correct result. Therefore, we recommend that you avoid loop query in your practice.

Use Query Efficiently

With the powerful query APIs, you can get the same result by using different query methods.

For example, you can use one of the following methods to query VM instances that are running on a host with the host UUID e497e90ab1e64db099eea93f998d525b.

Method 1:

QueryVmInstance hostUuid=e497e90ab1e64db099eea93f998d525b

Method 2:

QueryVmInstance host.uuid=e497e90ab1e64db099eea93f998d525b

In the above two methods, Method 1 is more effective because it queries a primitive field that only involves the VM instance inventory table. Method 2 is an expanded query that joins both the VM instance inventory table and the host inventory table.

When you use UUID as the query condition, we recommend that you query a primitive field instead of the sub-field of an expanded field.

Examples

Normal Query

QueryVmInstance defaultL3NetworkUuid=7e52c8b7b6f94e4485a61f3f1a8bfe42
QueryPortForwardingRule protocolType=TCP

Query Count

QueryVmInstance defaultL3NetworkUuid=7e52c8b7b6f94e4485a61f3f1a8bfe42 count=true
QueryPortForwardingRule protocolType=TCP count=true

Normal Query with Count

QueryVmInstance defaultL3NetworkUuid=7e52c8b7b6f94e4485a61f3f1a8bfe42 replyWithCount=true
QueryPortForwardingRule protocolType=TCP replyWithCount=true

Set Limit

QueryVmInstance defaultL3NetworkUuid=7e52c8b7b6f94e4485a61f3f1a8bfe42 limit=3
QueryPortForwardingRule protocolType=TCP limit=2

Set Condition

QueryVmInstance name~=clone
QueryPortForwardingRule vipPortStart?=23,24

Set Start

QueryVmInstance imageUuid=4b5e37a47a402977a3b285ccecf9c0c1 start=2 limit=3
QueryPortForwardingRule protocolType=TCP start=1 limit=3

Select Field

QueryVmInstance fields=name,uuid clusterUuid=5cac8330d5ab4c2ea393b8c3986c8850
QueryPortForwardingRule fields=uuid,privatePortStart,privatePortEnd vipPortStart=23 vipPortEnd=23

Sort

QueryVmInstance clusterUuid=5cac8330d5ab4c2ea393b8c3986c8850 sortBy=createDate sortDirection=asc
QueryPortForwardingRule sortBy=privatePortStart sortDirection=desc

Next Chapter:Resource Pool