==================
Tag Query Languag
==================
== by examples ==
seblu> list id                  #list all ids, same as list
seblu> list a                   #list all accounts
seblu> list h:fw*               #list all hostname starting by fw
seblu> list r=hv                #list all hypervisor
seblu> list r=vm                #list all vm
seblu> list hv=toto             #list vm of hypervisor toto
seblu> list hv=toto&h=chiche    #list vm chiche of hypervisor toto
seblu> list r=vm&cpu=2          #list vm with 2 cpu
seblu> list r=vm&cpu=2&mem>10g  #list vm with 2 cpu and mem > 10g
seblu> list r=hv&cpu=2&mem>10g  #list hypervisor with no vm
seblu> list cpu>=2$pop$alloc    #list object with at least 2cpu and show tags pop and alloc
seblu> list r=vm^10             #list first 10 vm
seblu> list r=vm^:10            #list last 10 vm
seblu> list r=vm^5:10           #list vm
seblu> list r=vm%vm             #list vm sorted by vm
seblu> list r=vm%vm%cpu         #list vm sorted by vm and cpu
seblu> list r=vm&-cpu           #list vm without tag cpu
seblu> list a-con               #list disconnected account

== Basics ==
- TQL build a list of objects in one query
- An object is a list of tags
- TQL can select and sort object by tags
- TQL can choose tags in object
- TQL can limit number of objects to select
- TQL is a list statement mixed by separators
- TQL build his object list from left to right (left parenthesis)
- Each statement update the builded list regarding his separators
- Selecting, sorting and showing separators are followed by tags
- Limiting separators are followed by limiting conditions
- TQL always return id tag
- By default separators is &
- By default object list is sorted id

== Tags ==
- Every tag is composed by a tagname and a tagvalue
- Tagname are case insensitive, tagvalue is case sensitive
- You can use globin on tagname
- tagname starting by - means all tag except this one
- Operators machtes on tagvalues

== statement separators ==
& selection intersection
| selection union
/ selection complement
^ selection limit
$ tag showing
% tag sorting

== tags operators ==
= strict equality
: globing matching (no case)
~ regex matching
> superior strict
>= superior
< inferior
<= inferior strict
Each previous operators can be negated by adding ! before it.

== limiting conditions ==
n limit to n first objects
:n limit to last n objects
n:m limit from n to m objects

== number facility ==
10k = 1000
10ki = 1024
1m = 1000 ^ 2
1mi = 1024 ^ 2
1g = 1000 ^ 3
1gi = 1024 ^ 3

== reserverd tags ==
Reserved tags are tags with a special meaning and cannot be set or remove
directly by clients

id: object unique identifier (eg: kvmlab-1.test5)
a: account name (eg: bobby)
r: account role (host/hv/vm/cli/web/spv)
closed: account close status
con: connection uptime in seconds (eg: 3600)
lastcon: last connection date (timestamp)
lastdcon: last disconnection date (timestamp)
ip: ipv4 of connection
hv: hypervisor id (eg: kvmlab-1)

== well known tags ==
h: hostname (eg: access)
htype: hypervisor type (xen/kvm)
libvirtver: Libvirt version
status: VM status (running/paused/stopped)
cpu: cpu count
cpualloc: allocated cpu count
cpuremaining: remaining CPU available for allocation
cpuallocratio: ratio between allocated CPU and total CPU
mem: memory total size
memused: memory used
memfree: memory free
memremaining: remaining memory available for allocation
memallocratio: ratio between allocated memory and total memory
arch: hardware architecture (x86/x64)
uname: output of uname command
uptime: uptime of hostname
load: load average
os: operating system (linux/windows)
alloc: host is allowed to be selected to a migration
hvm: hardware virtualisation enabled
nvm: vm count on an hypervisor
vmstarted: started vm count on an hypervisor
vmstopped: stopped vm count on an hypervisor
vmpaused: paused vm count on an hypervisor
version: account reported version
sto: storage pool names (eg: vg fg)
stovg_type: vg storage pool type (eg: lvm)
stovg_size: vg storage pool size (eg: 1042)
stovg_used: vg storage pool used space (eg: 1)
stovg_free: vg storage pool free space (eg: 1041)
stovg_path: vg storage pool path (eg: /dev/vg/)
stovg_vol: vg storage pool volume list (eg: sex titi toto)
stovg_ratio: ratio between allocated storage size and total storage size
disk: disk index list (eg: 1 2 3 4)
disk1_path: disk 1 path (eg: /dev/vg/sex)
disk1_size: disk 1 size (eg: 1024)
disk1_pool: storage pool back reference (eg: vg) [vmonly]
disk1_vol: storage pool volume back reference (eg: titi) [vmonly]
vncport: vnc local port (eg: 5001)
hvver: hypervisor version (eg: 0.14)
hserial: host serial number (eg: Dell service tag)
hvendor: host vendor (eg: Dell Computer Corporation)
hmodel: host model (eg: PowerEdge 2850)
hbios: host bios version and/or date (eg: A05 (01/09/2006))
cputhread: total number of cpu thread
cpufreq: cpu core frequency
cpuuse: global cpu usage (percentage)
platform: python platform info
chaserial: blade chassis serial number (dell tag)
chaasset: blade chassis asset tag (dell tag)
chaslot: position in blade chassis (slot number)


== grammar ==
input: [ prop ] EOL
prop: "(" prop ")" | stat
stat: [ prop ] sep prop | [ prop ] mod word | clause
clause: word [ op word ]
sep: "&" | "|" | "/"
mod: "^" | "%" | "$"
op: "=" | "!=" |  ":" | "!:" | "~" | "!~" | ">" | ">=" | "<" | "<="