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, anddate. In the example above,uuid,name, andsystemare primitive fields. - A nested field includes other types except for the primitive types. In the example above,
ipRangesis a nested field.
Unless explicitly stated, every field of every inventory can be queried.
Every inventory has its corresponding query API, such as
QueryZone,QueryHost, andQueryVmInstance.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. |
|
0.6 | |
| replyWithCount | If true, the query response returns both the inventories and the inventory count. Default value: 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. |
|
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 | Optional | Valid Value | Starting Version |
|---|---|---|---|---|
| name | The field name. | 0.6 | ||
| op | The comparison operator. |
|
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
