Parameters

Query Condition

# 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

condition_name(no_space)CLI_comparison_operator(no_space)condition_value

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.

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.

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.

# 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.

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.

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

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.

QueryVmInstance hostUuid=e497e90ab1e64db099eea93f998d525b

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.

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