MozillaWiki

Bugzilla:BzAPI:Search: Difference between revisions

Bugzilla Discussion

Bugzilla:BzAPI:Search (view source)

Revision as of 02:05, 21 September 2016

2,315 bytes added ,  21 September 2016
Add deprecation notice
No edit summary
(Add deprecation notice)
 
(22 intermediate revisions by 5 users not shown)
Line 1: Line 1:
<div style="border: thin dotted #aaa; padding:5px;">
'''This specific REST API, generally referred to as "BzAPI", is DEPRECATED. For new projects, use the [[Bugzilla:REST_API|native REST API]] instead. The BMO team has implemented a [[Bugzilla:BzAPI:CompatLayer|compatibility layer]] to help existing apps transition off BzAPI onto the native REST API. Please migrate existing BzAPI-based apps to the new compatibility-layer endpoint as soon as possible, as BzAPI will be shut off at some point in the future. Direct any questions to the [[BMO]] team.
'''The native REST API is available in Bugzilla 5.0 and up, and on bugzilla.mozilla.org.  Although BzAPI is deprecated, it can be used with older Bugzilla installations (versions prior to 5.0) to provide a REST API.'''
</div><br>
This page defines the URL parameter interface for searching for bugs using the HTTP API (/bug GET). At the moment, the search API call does also support the field names from the web interface, to make it easy to port URLs and other code across. But if supporting this becomes difficult, it might go away.  
This page defines the URL parameter interface for searching for bugs using the HTTP API (/bug GET). At the moment, the search API call does also support the field names from the web interface, to make it easy to port URLs and other code across. But if supporting this becomes difficult, it might go away.  
Note that Bugzilla 4.2 and above limits the number of results returned on an initial search when using the HTML web interface (the default limit is 500). However, this limit does not apply to the interface BzAPI uses - you will always receive all results for your search.
==Single Value, Multiplicable==
For '''any single-valued [[Bugzilla:BzAPI:Objects#Bug|Bug]] field''' other than the ones specified below as being special, you can specify any number of individual discrete values as separate URL parameters with identical keys. Multiple values will be ORed together. This includes bug custom fields and (where it makes sense) also works for the field names given in the Boolean Charts section (attachments, comments, flags etc.).
Fields: '''product, component, severity, priority, etc. etc. etc.'''
E.g. component=XML&severity=critical&severity=blocker
Note that custom fields must be searched for using their official field names, not the descriptive name from the UI. The official name almost always begins with "cf_". So "cf_blocking_20", not "blocking2.0".
==Quick Search==
The '''quicksearch''' parameter uses QuickSearch syntax.


==Text Fields==
==Text Fields==


For the following fields, specify some text to search for along with a '''$FIELDNAME_type''' parameter with a value from the [[Bugzilla:REST_API:Search#Types|list of types]].
For the following fields, specify some text to search for. You may also specify a '''$FIELDNAME_type''' parameter with a value from the [[Bugzilla:BzAPI:Search#Types|list of types]]. If you do not, the default is ''contains_all'' for keywords, and ''contains_all_words'' for everything else.


Fields: '''comment, keywords, summary, url, whiteboard'''
Fields: '''comment, keywords, summary, url, whiteboard'''
Line 9: Line 31:
E.g. summary=Flash%20crash&summary_type=contains_all_words
E.g. summary=Flash%20crash&summary_type=contains_all_words


They keywords search will complain if your words are not valid keywords.
The keywords search will complain if your words are not valid keywords.


==Person Fields==
==Person Fields==


Specify up to two strings, as '''email1''' and '''email2''', and then specify the fields in which to search for those strings (booleans - set to 1 if wanted), and the type of search to do ('''emailN_type''') from the [[Bugzilla:REST_API:Search#Types|list of types]]. You can specify multiple email addresses, comma-separated.
Specify up to two strings, as '''email1''' and '''email2''', and then specify the fields in which to search for those strings (using booleans such as '''email1_creator''' - set to 1 if wanted), and the type of search to do ('''emailN_type''') from the [[Bugzilla:BzAPI:Search#Types|list of types]]. You can specify multiple email addresses, comma-separated.


Fields: '''email1, email2, emailN_type, emailN_assigned_to, emailN_qa_contact, emailN_reporter, emailN_cc, emailN_comment_author'''
Fields: '''email1, email2, emailN_type, emailN_assigned_to, emailN_qa_contact, emailN_creator, emailN_cc, emailN_comment_creator'''


E.g. email1=fred@example.com,wilma@example.com&email1_type=equals_any&email1_assigned_to=1&email1_qa_contact=1
E.g. email1=fred@example.com,wilma@example.com&email1_type=equals_any&email1_assigned_to=1&email1_qa_contact=1
Line 21: Line 43:
==Bug ID==
==Bug ID==


Specify '''id'''=<comma-separated list>, and an '''id_mode''' of either ''include'' or ''exclude''. You may instead pass a separate '''id''' parameter for each bug ID if you wish. Note that this field does not support aliases.
Specify '''id'''=<comma-separated list>, and an '''id_mode''' of either ''include'' or ''exclude'' (defaults to ''include''). You may instead pass a separate '''id''' parameter for each bug ID if you wish. Note that this field does not support aliases.
 
If you specify only IDs as your search criteria, you will get back full [[Bugzilla:REST_API:Objects#Bug|Bug]] objects instead of the limited number of fields normally provided on the search interface. This is a shortcut to allow the retrieval of full bug information for multiple bugs without having to make multiple requests.
 
E.g. id=3,4,5,6 (full Bug objects returned)<br>
E.g. id=3,4,5,6&id_mode=include&priority=P1 (normal search results returned)


==Deadline==
==Deadline==
Line 32: Line 49:
Specify a range with '''deadline_after''' and '''deadline_before'''. (Note: implementation is actually 'on or before' and 'on or after'; this may change, so be warned).
Specify a range with '''deadline_after''' and '''deadline_before'''. (Note: implementation is actually 'on or before' and 'on or after'; this may change, so be warned).


E.g. deadline_after=2008-08-08&deadline_before=2009-09-09
E.g. deadline_after=2008-02-17&deadline_before=2009-12-31


==Changes==
==Changes==
Line 38: Line 55:
You can also ask for bugs that have changed in a particular date range, using '''changed_after''' and/or '''changed_before'''. If you do, you may additionally specify that a particular field has changed in that time using '''changed_field''', and if you do that, you may also set '''changed_field_to''' to specify the new value. If you don't specify a field, it tells you whether the last_change_time is in the range given.
You can also ask for bugs that have changed in a particular date range, using '''changed_after''' and/or '''changed_before'''. If you do, you may additionally specify that a particular field has changed in that time using '''changed_field''', and if you do that, you may also set '''changed_field_to''' to specify the new value. If you don't specify a field, it tells you whether the last_change_time is in the range given.


Set "changed_field" to "creation_time" in order to look for bugs filed between certain dates.
Set "changed_field" to "creation_time" in order to look for bugs filed between certain dates. (It is not possible to do a search which looks for an exact creation time, using a single parameter. If you want to search for an exact creation_time, use Boolean Charts.)
 
E.g. changed_after=2008-08-08&changed_before=2009-09-09&changed_field=priority&changed_field_to=P1


==Single Value, Multiplicable==
E.g. changed_after=2008-03-31&changed_before=2009-10-31&changed_field=priority&changed_field_to=P1
 
For '''any other single-valued field''', including custom fields and (where it makes sense) the field names given below for use with Boolean Charts, you can specify any number of individual discrete values as separate URL parameters with identical keys. Multiple values will be ORed together.
 
E.g. component=XML&severity=critical&severity=blocker


==Boolean Charts==
==Boolean Charts==


The Bugzilla "boolean charts" mechanism is the way to construct more complex queries, or to search on other fields which do not have their own dedicated parameters (e.g. time tracking fields, attachment fields, flags, history, groups and related bugs).
The Bugzilla "boolean charts" mechanism is the way to construct more complex queries, e.g. ones where you want a search type other than a simple "equals".


The parameters for each triple are '''fieldA-B-C''', '''typeA-B-C''' and '''valueA-B-C''', where A, B and C are integers beginning at 0.  
The parameters for each triple are '''fieldA-B-C''', '''typeA-B-C''' and '''valueA-B-C''', where A, B and C are integers beginning at 0.  
Line 68: Line 79:
Note that you can't construct a Boolean Chart where the "value" is the empty string. One way to get around this is to use a regex match for "^$".
Note that you can't construct a Boolean Chart where the "value" is the empty string. One way to get around this is to use a regex match for "^$".


You may search many [[Bugzilla:REST_API:Objects#Attachment|attachment fields]] by specifying a field of "attachment.<fieldname>". The exceptions are  creation_time, encoding, the ids, the refs, size and token. Flags on either attachments or bugs are searched for using the same fields below. Additional field values you can use are:
You may search many [[Bugzilla:BzAPI:Objects#Attachment|attachment fields]] by specifying a field of "attachment.<fieldname>". The exceptions are  creation_time, encoding, the ids, the refs, size and token. Flags on either attachments or bugs are searched for using the same fields below. Additional field values you can use are:


{| border="1"
{| border="1"
Line 79: Line 90:
|content||Full text of bug; use with special 'matches' type
|content||Full text of bug; use with special 'matches' type
|-
|-
|idle||Time since bug was last changed by anyone, in days
|idle||Time since bug was last changed by anyone, in days (Note: the format of this parameter may change in the future)
|-
|-
|flag||Name of a flag (on a bug or attachment)
|flag||Name of a flag (on a bug or attachment)
Line 87: Line 98:
|flag.setter||Person who set a flag (name)
|flag.setter||Person who set a flag (name)
|-
|-
|assignee_idle||Time since bug was last changed by assignee; postfix number with h/d/w/m/y to specify units
|assignee_idle||Time since bug was last changed by assignee; postfix number with h/d/w/m/y to specify units (Note: the format of this parameter may change in the future)
|}
|}


==Types==
==Types==


Search type values you can use are:
The search type values you can use are as follows.
 
Note that when it says "any of the strings" or "all of the strings", strings are space-separated. So you can't search for a literal string containing a space this way. If you are using multiple parameters, e.g. "component=Foo%20Bar&component=Baz", you get an OR semantic across the parameters by default, even when you use "equals". If you use "contains any of the strings" in that case, because of the space, you'll get every bug in a component whose name contains "Foo", "Bar" or "Baz".


{| border="1"
{| border="1"
Line 99: Line 112:
|equals||is equal to||
|equals||is equal to||
|-
|-
|not_equals||is not equal to||
|notequals||is not equal to||
|-
|-
|equals_any||is equal to any of the strings||
|equals_any||is equal to any of the strings||
|-
|-
|contains||contains the string||
|contains||contains the string|| use 'substring' for search params
|-
|-
|not_contains||does not contain the string||
|not_contains||does not contain the string|| use 'notsubstring' for search params
|-
|-
|case_contains||contains the string (exact case)||
|case_contains||contains the string (exact case)||
Line 117: Line 130:
|contains_any_words||contains any of the words||
|contains_any_words||contains any of the words||
|-
|-
|not_contains_any_words||contains none of the words||
|not_contains_any_words||contains none of the words|| use 'nowords' in search params
|-
|-
|contains_all_words||contains all of the words||
|contains_all_words||contains all of the words||
Line 140: Line 153:
|-
|-
|matches||matches||Full text of bug contains the string; use only with special 'content' field
|matches||matches||Full text of bug contains the string; use only with special 'content' field
|-
|isempty||isempty||Field is empty; "value" is ignored (note: should be 'empty' for consistency, but isn't yet)
|-
|isnotempty||isnotempty||Field is not empty; "value" is ignored (note: should be 'not_empty' for consistency, but isn't yet)
|}
|}
Mcote
Confirmed users
1,927

edits

Retrieved from "https://wiki.mozilla.org/Special:MobileDiff/185649...1148494"