Overview

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


Architecture

Every resource in ZStack 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 Optional 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 Optional Optional 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, 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, 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 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 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 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
Download

Already filled the basic info? Click here.

Enter at least 2 characters.
Invalid mobile number.
Enter at least 4 characters.
Invalid email address.
Wrong code. Try again. Send Code Resend Code (60s)

The download link will be sent to your email. Make sure the address you provided is valid and correct.

Download

Not filled the basic info yet? Click here.

Invalid email address or mobile number.

Email Us

contact@zstack.io
ZStack certification training consulting
Enter at least 2 characters.
Invalid mobile number.
Enter at least 4 characters.
Invalid email address.
Wrong code. Try again. Send Code Resend Code (60s)

Email Us

contact@zstack.io

The download link is sent to your email address.

If you don't see it, check your spam folder, subscription folder, or AD folder. After receiving the email, click the URL to download the documentation.

The download link is sent to your email address.

If you don't see it, check your spam folder, subscription folder, or AD folder.
Or click on the URL below. (For Internet Explorer, right-click the URL and save it.)

Thank you for using ZStack products and services.

Submit successfully.

We'll connect soon.

Thank you for choosing ZStack products and services.

Back to Top