wiki:TracQuery

Trac Ticket Queries

In addition to reports, Trac provides support for custom ticket queries, used to display lists of tickets meeting a specified set of criteria.

To configure and execute a custom query, switch to the View Tickets module from the navigation bar, and select the Custom Query link.

Filters

When you first go to the query page the default filters will display all open tickets, or if you're logged in it will display open tickets assigned to you. Current filters can be removed by clicking the button to the right with the minus sign on the label. New filters are added from the pulldown list in the bottom-right corner of the filters box. Filters with either a text box or a pulldown menu of options can be added multiple times to perform an or of the criteria.

You can use the fields just below the filters box to group the results based on a field, or display the full description for each ticket.

Once you've edited your filters click the Update button to refresh your results.

Clicking on one of the query results will take you to that ticket. You can navigate through the results by clicking the Next Ticket or Previous Ticket links just below the main menu bar, or click the Back to Query link to return to the query page.

You can safely edit any of the tickets and continue to navigate through the results using the Next/Previous/Back? to Query links after saving your results. When you return to the query any tickets which were edited will be displayed with italicized text. If one of the tickets was edited such that it no longer matches the query criteria the text will also be greyed. Lastly, if a new ticket matching the query criteria has been created, it will be shown in bold.

The query results can be refreshed and cleared of these status indicators by clicking the Update button again.

Saving Queries

While Trac does not yet allow saving a named query and somehow making it available in a navigable list, you can save references to queries in Wiki content, as described below.

You may want to save some queries so that you can come back to them later. You can do this by making a link to the query from any Wiki page.

[query:status=new|assigned|reopened&version=1.0 Active tickets against 1.0]

Which is displayed as:

Active tickets against 1.0

This uses a very simple query language to specify the criteria (see Query Language).

Alternatively, you can copy the query string of a query and paste that into the Wiki link, including the leading ? character:

[query:?status=new&status=assigned&status=reopened&group=owner Assigned tickets by owner]

Which is displayed as:

Assigned tickets by owner

Using the [[TicketQuery]] Macro

The TicketQuery macro lets you display lists of tickets matching certain criteria anywhere you can use WikiFormatting.

Example:

[[TicketQuery(version=0.6|0.7&resolution=duplicate)]]

This is displayed as:

No results

Just like the query: wiki links, the parameter of this macro expects a query string formatted according to the rules of the simple ticket query language.

A more compact representation without the ticket summaries is also available:

[[TicketQuery(version=0.6|0.7&resolution=duplicate, compact)]]

This is displayed as:

No results

Finally if you wish to receive only the number of defects that match the query using the count parameter.

[[TicketQuery(version=0.6|0.7&resolution=duplicate, count)]]

This is displayed as:

0

Customizing the table format

You can also customize the columns displayed in the table format (format=table) by using col=<field> - you can specify multiple fields and what order they are displayed by placing pipes (|) between the columns like below:

[[TicketQuery(max=3,status=closed,order=id,desc=1,format=table,col=resolution|summary|owner|reporter)]]

This is displayed as:

Results (1 - 3 of 409)

1 2 3 4 5 6 7 8 9 10 11
Ticket Resolution Summary Owner Reporter
#414 fixed RESTful operation and link parameter changes draft-ietf-core-resource-directory@… lauri.piikivi@…
#413 fixed Make Simple Directory Discovery really simple draft-ietf-core-resource-directory@… kovatsch@…
#412 fixed Simple Directory Discovery text draft-ietf-core-resource-directory@… kovatsch@…
1 2 3 4 5 6 7 8 9 10 11

Full rows

In table format you can also have full rows by using rows=<field> like below:

[[TicketQuery(max=3,status=closed,order=id,desc=1,format=table,col=resolution|summary|owner|reporter,rows=description)]]

This is displayed as:

Results (1 - 3 of 409)

1 2 3 4 5 6 7 8 9 10 11
Ticket Resolution Summary Owner Reporter
#414 fixed RESTful operation and link parameter changes draft-ietf-core-resource-directory@… lauri.piikivi@…
Description

Hi,

Some thought son the device registry. Started with making it more RESTful api, and expanded on the way to expressing more information as link parameters, and utilizing existing link parameters.

  1. change the URL shceme to be more RESTful, resources in URL path, not in query parameters
  2. Proposal that lifetime, lt, is a new link-format parameter
  3. endpoint as URI in link-format payload for registration, in URL path segment for lookup (no ep parameter as in draft, ep was used as query parameter and link parameter)
  4. Collection (aka "domain") and group expressed as link parameters (no d, gp parameters as in draft)

I also would like to see the "domain" parameter changed to more neutral collection. It forces clarity to the usage of domain in DNS vs as collection of endpoints in RD. The domain usage seemed confusing to me. It may or may not be a DNS domain in the end.

Sincerely,

  • Lauri Piikivi

# Link parameters ## Endpoint as the first target URI The first link in link-format is the endpoint name.

<coap://node1/>;lt=600

It can have domain

<coap_tcp://node1.example.com/>

Justification: endpoint is the base-link to the related resources in the endpoint. Expressing it as link is logical.

Note, it an endpoint does not have static DNS entry or name, the RD can return in registration response a link, with explicit relation "host", that is the registered link to the endpoint. For example endpoint can learn the RD seen IP address in NAT environment, or RD can indicate back the DNS name for the endpoint.

Discussion Endpoint can have multiple schemes, coap over UDP, coap over DTLS, coap over TCP. Are these 1 registration (1 location) or do they need to be registered separately? draft has ep as link parameter, ch 7.1 page 25

## New link parameter: lifetime lt := Lifetime (optional). Lifetime of the registration in seconds. Range of 60-4294967295. If no lifetime is included, a default value of 86400 (24 hours) SHOULD be assumed. If resource link for an endpoint does not define own lt, the endpoint lt MUST be assumed.

Justification: the lifetime is a parameter of the endpoint link, and for the resource links at the endpoint.

Discussion Gives the possibility that resources may have different lifetime than the endpoint host. Those can be updated in RD

## Domain and group as Collection link parameter Collection and item link parameters are defined in RFC6573. Since the RD grouping of endpoints does not necessarily imply DNS domain usage, the logical grouping of endpoints into collections and groups is clearer. The relation can be also expressed in link parameters. Endpoint information, when retrieved from RD, can give the collection and group links for and endpoint. The links are URIs to the RD, with the relation parameter "collection" See https://tools.ietf.org/html/rfc6573#section-2.2 Domain, as used in draft, is "collection". Group is a expressed as "collection item"

Groups are links, and can express the Name, Scheme, IP, Port. In registration the RD may return link-format document, and endpoint can learn additional information of the groups and collection it belongs to from that link-format.

Most often the collection information is only used in the URL PATH to the endpoint. However, being able to read the registration data with collection information may help use cases for persistent storage of information and when reverse lookup from endpoint (or resoure) to the collections it belongs to are needed

# Resource Directory Operations ## Device Registration Method: POST URI Template: /rd/ep/EP_INSTANCE

## Registration path components rd/ep := RD Function Set path for endpoints (mandatory). This is the path of the RD Function Set, as obtained from discovery. An RD SHOULD use the value "rd" for this variable whenever possible. The mandatory segment "ep" is used to indicate endpoint related registration, update or query operations in the information hierarchy.

EP_INSTANCE := The endpoint name (mandatory). The maximum length of this parameter is 63 bytes.

After registration the endpoint name is an identifier that MUST be unique within a domain. RD service may return unique domain path and endpoint name in HTTP locator field, which MUST be used as the identifier from there on by the endpoint. An endpoint may get new locator in registration (for example if an endpoint resets and performs registration anew, while the old regstration is still valid for lifetime)

## Registration payload All other data, including context (link) are given in payload.

## Examples The following example shows an endpoint with the name "node1" registering two resources to an RD using this interface. Context, scheme, authority and port is given as a link with the new lifetime parameter.

Req: POST coap://rd.example.com/rd/ep/node1 Content-Format: 40 Payload: <coap://node1.example.com:5683">;lt=600 </sensors/temp>;ct=41;rt="temperature-c";if="sensor", </sensors/light>;ct=41;rt="light-lux";if="sensor"

Res: 2.01 Created Location: /rd/ep/node1

Device name is not unique, and the created resource for the device is named by the RD and device is found from path /ep/node1_1. Device does not have a domain name, so the RD acting as proxy inserts own context information to the registration

Req: POST /rd/ep/node1 HTTP/1.1 Host : example.com Content-Type: application/link-format Payload: <coap://node1.example.com:5683">;lt=600 </sensors/temp>;ct=41;rt="temperature-c";if="sensor", </sensors/light>;ct=41;rt="light-lux";if="sensor"

Res: 201 Created Location: /rd/ep/node1_1

Further references to the device MUST use the location /ep/node1_1

## Registration Update

URI Template: /{+location}

URI Template Variables: location := This is the Location path returned by the RD as a result of a successful earlier registration.

P lt := Lifetime (optional). Lifetime of the registration in seconds. Range of 60-4294967295. If no lifetime is included, a default value of 86400 (24 hours) SHOULD be assumed. lt is kept as variable as it is not a hierarchical part of resource name

Req: PATCH /rd/ep/node1_1

Res: 2.04 Changed

With explicit lt parameter

Req: PATCH /rd/ep/node1_1?lt=600

Res: 2.04 Changed

## Registration Change

The following example shows an endpoint updating its registration with a new context, changing an existing link, and adding a new link using this interface. Lifetime is updated as another call. With the initial registration the client set the following values: o lifetime (lt)=500 o context base-link=coap://local-proxy-old.example.com:5683 o resource= </sensors/temp>;ct=41;rt="foobar";if="sensor"

Req: PATCH /rd/ep/node1 Content-Format: 40 Payload: <coap://local-proxy.example.com:5683">;lt=1200 </sensors/temp>;ct=41;rt="temperature-f";if="core.s core.p custom-sensor", </sensors/door>;ct=41;rt="door";if="core.s custom-sensor"

Res: 2.04 Changed

# Resource Lookup

## General on the URL format URI Template may have domain. High level hierarchy is

rd-lookup-base/collection/group/endpoint/resource/interface

In shorter format, which SHOULD be supported the hierarchy is expressed as

rdlu/c/gp/ep/res/inf

With the formalization work for interfaces, they are raised to explicit parts of the information hierarchy.

## lookups to logical collections These lookups return links to RD logical collections. A client must further query the RD for a list of endpoints in the logical collection

These queries return a list of logical collections in the RD (links to RD with parameter rel="collection")

### lookup endpoint types, resource types and interface types

Req /rdlu/rt/

Returns a list of link-formats, to different resource types known by the RD

Resp </rdlu/rt/temperature> </rdlu/rt/door>

Req /rdlu/et/ Resp </rdlu/et/power-node> </rdlu/et/movement-detectors>

Req /rdlu/if/ Resp </rdlu/if/core.s> </rdlu/if/core.a> </rdlu/if/custom-sensor>

Further call to e.g. /rdlu/rt/door/ or /rdlu/if/core.s/ would return a list of endpoint links that have registered that resource type

###lookup all collections (formerly "domains")

/rdlu/c/

Returns EITHER a list of groups in the collection (links to RD with parameter rel="collection item") OR links to endpoints

Discussion

it is not possible to have a collection with direct children of groups and endpoints both

## lookup endpoints As the endpoint is the host of resources, queries to path segment ep and lower (/ep, /ep/INSTANCE/res, ep/INSTANCE/res/INSTANCE/if) return links to endpoints, which a client can directly use to communicate with a endpoint.

Note, that in practise the endpoint link can be to a proxy or gateway.

Discussion Should the GW or proxy be expressed explicitly with a VIA link relation for an endpoint? Assuming it it often known by the RD that the system has a GW or proxy

###lookup all endpoints in collection COL_A

/rdlu/c/COL_A/ep/

It is expected that the common structure is more flat, and endpoints can be often listed directly, collection is optional.

###lookup all endpoints

/rdlu/ep/

###lookup all resources in endpoint EP_A

/rdlu/ep/EP_A/res/

###lookup all resource types in specific resource

/rdlu/ep/EP_A/res/RES_3/if/

###lookup all resources in endpoint types HOME_SENSOR ???

/rdlu/et/HOME_SENSOR/res

/rdlu/c/COL_A/gp/ #lookup groups in collection /rdlu/c/rt/ # lookup resource types in collection

## URI Query part to lookups

URI QUERY PART: ?page,count and count are query filters. They are used as query parameters, since they are not resource selection but modify the amount of data shown for a path identifier.

# Examples

## Logical group lookups The following example shows a client performing a lookup for endpoints in sepcific endpoint type:

Req: GET /rdlu/et

Res: 2.05 Content </power-node>;et="power-node";rel="collection", </actuator>;et="actuator";rel="collection"

The following example shows a client performing a collection (previously domain) lookup:

Req: GET /rdlu/c

Res: 2.05 Content </collection1>;rel="collection", </collection2>;rel="collection"

The following example shows a client performing a group lookup for groups in collection:

Req: GET /rdlu/c/collection1/gp

Res: 2.05 Content </lights1>;rel="collection item", </lights2>;rel="collection item"

## Endpoint lookups

The following examples show endpoint queries for certain interface and resource type

Req: GET /rdlu/if/core.s Res: 2.05 Content <coap://[FDFD::123]:61616/temp>;rt="temperature"

Req: GET /rdlu/rt/temperature Res: 2.05 Content <coap://[FDFD::123]:61616/temp>;rt="temperature"

The following example shows a client performing a lookup for endpoints in sepcific endpoint type:

Req: GET /rdlu/et/power-node

Res: 2.05 Content <coap://[FDFD::123]:61616>, <coap://[FDFD::123]:61616>

The following example shows a client performing a lookup for all endpoints in a particular group:

Req: GET /rdlu/gp/lights1/

Res: 2.05 Content <coap://[FDFD::123]:61616>, <coap://[FDFD::124]:61616>

## Endpoint information query The following example shows a client performing a lookup for all groups an endpoint belongs to. To do this, the specific endpoint information is queried and collection and group information is parsed from the link-format. It is expected that this kind of reverse lookups are rare.

Req: GET /rdlu/ep/node1

Res: 2.05 Content Content-Format: 40 Payload: <coap://node1.example.com:5683">;lt=1200 </sensors/temp>;ct=41;rt="temperature-f";if="core.s core.p custom-sensor", </sensors/door>;ct=41;rt="door";if="core.s custom-sensor", <coap://rd.example.com/c/collection1>;rel="collection",<coap://rd.example.com/c/collection1/gp/group1>;rel="collection item", <coap://rd.example.com/c/collection1/gp/group2>;rel="collection item"

#413 fixed Make Simple Directory Discovery really simple draft-ietf-core-resource-directory@… kovatsch@…
Description

Currently the Simple Directory Discovery allows two modes:

  • Empty POST and the RD takes care
  • POST with payload with only selected resources

When the device is aware which resources it wants to expose and can perform POSTs with potentially large payloads (->Block1), it can be expected to perform a normal registration in my opinion. If some resources should be private/hidden, why have them in /.well-known/core (there is always the possibility for incremental discovery at other resources).

Thus, I recommend to remove the second mode (POST with payload).

Furthermore, I would move this "Simple Registration" into its own sub-section (after 4.1 Finding a Directory Server). There, we should also have some text that the RD then has to make some guesses about the lifetime an take care of such registrations by itself (periodic updates, de-registration).

#412 fixed Simple Directory Discovery text draft-ietf-core-resource-directory@… kovatsch@…
Description

The current text is misleading:

Not all endpoints hosting resources are expected to know how to implement the Resource Directory Function Set (see Section 5) and thus explicitly register with a Resource Directory

This means they explicitly register with a RD because they do not understand the Function Set... Proposal:

Not all endpoints hosting resources are expected to know how to implement the Resource Directory Function Set (see Section 5), and hence cannot register with a Resource Directory.

I also thought we wanted to get rid of the Function Set mechanics altogether?

1 2 3 4 5 6 7 8 9 10 11

Query Language

query: TracLinks and the [[TicketQuery]] macro both use a mini “query language” for specifying query filters. Basically, the filters are separated by ampersands (&). Each filter then consists of the ticket field name, an operator, and one or more values. More than one value are separated by a pipe (|), meaning that the filter matches any of the values.

The available operators are:

= the field content exactly matches the one of the values
~= the field content contains one or more of the values
^= the field content starts with one of the values
$= the field content ends with one of the values

All of these operators can also be negated:

!= the field content matches none of the values
!~= the field content does not contain any of the values
!^= the field content does not start with any of the values
!$= the field content does not end with any of the values

See also: TracTickets, TracReports, TracGuide

Last modified 9 years ago Last modified on Mar 10, 2010, 3:10:29 AM