EyeQL Reference Guide

FishEye contains a powerful query language called EyeQL. EyeQL is an intuitive SQL-like language that allows you to write your own specific queries. See examples.

EyeQL allows you to perform complex searches either within the Advanced Search or incorporated in scripts when programming the FishEye API.

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:

Notes: reviews applies to Crucible reviews.

aggregate-return-field:

The aggregate field to return.

Notes:

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.

Examples

The following examples demonstrate using EyeQL to extract information from your repository.

Find files removed on the Ant 1.5 branch:
select revisions where modified on branch ANT_15_BRANCH and is dead group by changeset

As above, but just return the person and time the files were deleted:
select revisions where modified on branch ANT_15_BRANCH and is dead return path, author, date

Find files on branch and exclude delete files:
select revisions where modified on branch ANT_15_BRANCH and not is deleted group by changeset

Find changes made to Ant 1.5.x after 1.5FINAL:
select revisions where on branch ANT_15_BRANCH and after tag ANT_MAIN_15FINAL group by changeset

Find changes made between Ant 1.5 and 1.5.1:
select revisions where between tags (ANT_MAIN_15FINAL, ANT_151_FINAL] group by changeset

As above, but show the history of each file separately:
select revisions where between tags (ANT_MAIN_15FINAL, ANT_151_FINAL] group by file

Find Java files that are tagged ANT_151_FINAL and are head on the ANT_15_BRANCH: (i.e. files that haven't changed in 1.5.x since 1.5.1)
select revisions from dir /src/main where is head and tagged ANT_151_FINAL and on branch ANT_15_BRANCH and path like *.java group by changeset

Find changes made by conor to Ant 1.5.x since 1.5.0:
select revisions where between tags (ANT_MAIN_15FINAL, ANT_154] and author = conor group by changeset

Find commits that do not have comments:
select revisions from dir / where comment = "" group by changeset

Find the 10 most recent revisions:
select revisions order by date desc limit 10

Find the 5th, 6th & 7th revisions:
select revisions order by date limit 4, 3

Find commits between two dates:
select revisions where date in [2008-03-08, 2008-04-08]

Find revisions that do not have any associated review:
select revisions where (not in any review)

Return number of matched revisions, the number of files modified, authors who modified code, changesets, tags, and reviews:

select revisions
where date in [ 2003-10-10, 2004-12-12 ]
return count(revisions), count(distinct path), count(distinct author), count(distinct csid), count(distinct tags), count(distinct reviews)

As Sub-totals for each distinct changeset, Return csid, the author, date, comment, number of matched revisions, the number of files modified, the lines added/removed:

select revisions
where date in [ 2003-10-10, 2004-12-12 ]
group by changeset
return csid, author, date, comment, count(revisions), count(distinct path), sum(linesAdded), sum(linesRemoved)

For each matched file, return the file name, number of matched revisions, the lines added/removed:

select revisions
where date in [ 2003-10-10, 2004-12-12 ]
group by file
return path, count(revisions), sum(linesAdded), sum(linesRemoved)

Show all the changesets with no review:

select revisions
from dir /
where not reviewed
group by changeset
return csid, author, count(revisions), comment

Child pages

EyeQL Reference Guide

Examples