EyeQL Reference Guide

query:

select revisions
(from (dir|directory) word)?
(where clauses)?
(order by date (asc | desc)? )?
Notes: asc produces 'ascending order'.
desc produces 'descending order'.
(group by (file|dir|directory|csid|changeset))?
(return return-clauses)?
(limit limit-args)?

clauses:

clause ((or|and|,) clause)*
Notes:
and binds more tightly than or.
',' (comma) means 'and'.

clause:

(clauses)

not clause

path (not)? like word
Notes:
word is an Antglob.

path = word
Notes:
Defines an exact path without wildcards or variables. path must represent a complete (hard-coded) path.

path != word
Notes:
Defines an exact path exclusion without wildcards or variables. path must represent a complete (hard-coded) path.

date in ( ( | [ ) dateExp, dateExp ( ) | ] )
Notes: The edges are
  inclusive if [ or ] is used.
  exclusive if ( or ) is used.

date dateop dateExp
Notes:
dateop can be <, >, <=, >=, =, == or != .

author = word

author in (word-list)

comment matches word
Notes:
Does a full-text search.

comment = string
Notes:
Matches string exactly.
Most comments end in a new line, so remember to add \n at the end of your string.

comment =~ string
Notes:
string is a regular expression.

content matches word
Notes:
Does a full-text search.
At this time searches are restricted to HEAD revisions.

(modified|added|deleted)? on branch word
Notes:
Selects all revisions on a branch.
modified excludes the branch-point of a branch.
added selects all revisions on the branch if any revision was added on the branch.
deleted selects all revisions on the branch if any revision was deleted on the branch.

tagged op? word
Notes:
op can be <, >, <=, >=, =, == or != .
op defaults to == if omitted.
These operators are 'positional' and select revisions that appear on, after, and/or before the given tag.

between tags tag-range

after tag word

before tag word

is head (on word)?
Notes:
This selects the top-most revision on any branch, if no branch is specified.

is ( dead | deleted )
Notes:
Means the revision was removed/deleted.

is added
Notes:
Means the revision was added (or re-added).

csid = word
Notes:
Selects all revisions for the given changeset ID.

p4:jobid = word
Notes: finds revisions whose Perforce jobid is word.

p4:jobid =~ word
Notes: finds revisions whose Perforce jobid matches regex word.

reviewed
Notes: (applies to Crucible reviews) alias for in or before any closed review.

(in | before | in or before) review word

(in | before | in or before) any (review states)? review

Notes:
word is a review key.
in selects reviewed revisions. If a review contains a diff, then only the most recent revision is considered in the review.
before selects all revisions in a file prior to the revision in the review.
review states is a comma-separated list of open, closed, draft.

tag-range:

( ( | [ ) T1:word, T2:word ( ) | ] )
Notes:
A range of revisions between those tagged T1 and T2.
The edges are:
  inclusive if [ or ] is used.
  exclusive if ( or ) is used.
You can mix edge types. These are all valid: (T1,T2), [T1,T2], (T1,T2] and [T1,T2).

Having trouble with Subversion tags? See How Tags Work in Subversion for more information.

word:

Any string, or any non-quoted word that does not contain white space or any other separators.

string:

A sequence enclosed in either " (double quotes) or ' (single quotes).
The following escapes work: \' \" \n \r \t \b \f.
Unicode characters can be escaped with \uXXXX.
You can also specify strings in 'raw' mode like r"foo". (Similar to Python's raw strings. See Python's own documentation).

dateExp:

See our Date Expressions Reference Guide for more information on date formats.

return-clauses:

return-clause (, return-clause)*
A return clause signifies that you want control over what data is returned/displayed.

return-clause:

( path | dir | directory | revision | author | date | comment | csid | isBinary | totalLines | linesAdded | linesRemoved | isAdded | isDeleted | isCopied | isMoved | tags | reviews | aggregate)
( as word )?
The attribute to return, optionally followed by a name to use for the column.

Notes: reviews applies to Crucible reviews.

aggregate-return-field:

( count(revisions) | count(binary-field) | count(distinct other-field) | sum(numeric-field) | average(numeric-field) | max(numeric-field) | min(numeric-field) )

The aggregate field to return.

メモ:

binary-fields are isBinary, isAdded, isDeleted, isCopied, isMoved. e.g. count(isAdded) will return the number of added files.

numeric-fields are totalLines, linesAdded, linesRemoved.

other-field can be path, dir, author, date, csid, tags or reviews. e.g. count(distinct path) will return the number of unique paths. count(distinct tags) will return the number of unique tags.

If a group by is given, give sub-totals for each group.

With no group by clause, you can have:

• return normal columns
• return aggregates

With a group by changeset|csid clause:

• return normal columns
• return csid, comment, date, author, aggregates

With a group by file|path clause:

• return normal columns
• return path, aggregates

With a group by dir|directory clause:

• return normal columns
• return dir, aggregates

i.e. The EyeQL can contain a returns clause that contains all non-aggregate columns, or all aggregate columns.
Non-aggregate and aggregate columns can only be mixed if the columns are unique for the grouping.

limit-clause:

( length | offset, length | length offset offset )

Notes: Limits the number of results to return. offset specifies the starting point of the truncated result set and length specifies the set length. offset is zero-based.