Fedora Resource Index Search Service

Introduction

User Interface

1. Find Tuples

   The "Find Tuples" tab shown below is used to run tuple queries against the resource index. A tuple query is one that returns a list of named values.
   
   When you enter a query and click "Launch", a new browser window will display the results.
   To get an idea of how it works, try the following iTQL query, which asks for information about all Behavior Definition objects in the repository:

   select $object $modified from <#ri>
   where  $object <rdf:type> <fedora-model:FedoraBDefObject>
   and    $object <fedora-view:lastModifiedDate> $modified

   In response, you should see something like this:

   "object","modified"
   info:fedora/demo:DualResImage,2005-01-27T23:06:54.399
   info:fedora/demo:22,2005-01-27T23:06:57.449
   info:fedora/demo:12,2005-01-27T23:06:56.662
   info:fedora/demo:1,2005-01-27T23:07:00.528
   info:fedora/demo:27,2005-01-27T23:07:01.513
   info:fedora/demo:Collection,2005-01-27T23:06:58.42
   info:fedora/demo:19,2005-01-27T23:06:59.673
   info:fedora/demo:8,2005-01-27T23:07:38.978
   info:fedora/demo:15,2005-01-27T23:07:41.58

   This is a list of comma-separated values, each row representing the URI and modified date of the objects that matched the query.
   Above the query text box, you can alter several settings for a query. These settings are described below.

   • Language

     Indicates the query language to use. Currently, the only valid option is iTQL (a full-featured RDF query language supported by the Mulgara). SPARQL support is expected in a future release.

   • Response

     Indicates the desired response format. Valid options include:
     • CSV - Comma-separated values
     • Simple - A simple easy-to-read text format that shows datatype information, when present
     • TSV - Tab-separated values

   • Limit

     The maximum number of results to return. It is useful to set this low when testing queries.

   • Advanced

     • Force Distinct - Whether to force duplicate results to be dropped. Note: iTQL never returns duplicates.
     • Fake Media-Types - Whether to send incorrect Content-Type HTTP response headers with the responses (to trick browsers into displaying the results instead of popping up a "Save As/Open With" window).
     • Stream Immediately - Whether to stream the results right away (faster), or to save them to a temporary file before sending them to the client. The default behavior (to save the results before streaming) will give a more informative error message if a query fails.

2. Find Triples

   The "Find Triples" tab shown below is used to run triple queries against the resource index. A triple query is one that returns a list of RDF statements (aka triples).
   
   This tab works in much the same way as the "Find Tuples" tab, but supports different response formats and provides a means to convert tuple query results to triples. It also exposes another query language: SPO.

   • SPO

     This is a very simple RDF query language, where queries consist of a specific subject (or an asterisk, indicating "any"), a specific predicate (or an asterisk), and a specific object (or an asterisk). The easiest way to learn SPO is by example:

     Get all triples in the repository
     
         * * *
     
     Get all triples where the object is demo:1
     
         * * <info:fedora/demo:1>
     
     Get all triples where the subject is demo:1 and the object is demo:2
     
         <info:fedora/demo:1> * <info:fedora/demo:2>

   • Response Formats

     A variety of RDF formats are supported:
     • N-Triples - A subset of Notation 3 defined in the RDF Test Cases document.
     • Notation 3 - The original RDF text format, defined by Tim Berners-Lee in An RDF language for the Semantic Web.
     • RDF/XML - The "RDF/XML" format, defined in the RDF/XML Syntax Specification.
     • Turtle - A newer subset of Notation 3, defined in Dave Beckett's Turtle - Terse RDF Triple Language.

   • Using Templates

     Templates are used to convert tuple query results to triples. A template consists of one or more triple binding patterns that reference the binding variables in an iTQL query.
     The easiest way to understand how this works is by example.
     In this example, we'll show how to extract a subgraph from the resource index using iTQL. Enter the following query text:

     select $a $r $b from <#ri>
     where  $a <rdf:type> <fedora-model:FedoraObject>
     and    $a $r $b
     and    $b <rdf:type> <fedora-model:FedoraObject>

     This query by itself returns all relationships between data objects in a repository. The binding variables are $a, $r, and $b. Now enter the following in the template text box: $a $r $b When you launch the query, you'll see a list of triples: the sub-graph of all object-to-object relationships in the repository. (If you don't see anything, you should ingest the demo objects which include some sample relationships).
     Now try the following template instead. This demonstrates how to derive new statements from those in the resource index:

     $a <urn:example:isRelatedTo> $b
     $b <urn:example:isRelatedTo> $a

     Running the query will now show two statements for every object-to-object relationship in the resource index graph.
     Note: When using templates to transform tuples to triples, some duplicates may be returned. These can be avoided by checking "Force Distinct".

3. Show Aliases

   
   This tab shows the aliases that can be used in queries and what URI prefixes they map to.
   Aliases are just shortcuts that help make queries easier to write. For example, in a query you can write <fedora-model:state> instead of <info:fedora/fedora-system:def/model#state>.

Application Interface

• Square brackets ( "[" and "]" ) indicate that the parameter is optional.
• As with all HTTP parameters, unsafe URI characters should be URI-escaped. For reability purposes, URI escaping is not shown below.
• The query and template parameters optionally take the value by reference -- that is, a URL to a query or template can be given instead of the actual text.
• The flush parameter tells the resource index to ensure that any recently-added/modified/deleted triples are flushed to the triplestore before executing the query. This option can be desirable in certain scenarios, but for performance reasons, should be used sparingly when a process is making many API-M calls to Fedora in a short period of time: We have found that Mulgara generally achieves a much better overall update rate with large batches of triples.

1. Syntax for Requesting Tuples

   http://localhost:8080/fedora/risearch?type=tuples
                                        &flush=[true (default is false)]
                                        &lang=iTQL
                                        &format=CSV|Simple|Sparql|TSV
                                        &limit=[1 (default is no limit)]
                                        &distinct=[on (default is off)]
                                        &stream=[on (default is off)]
                                        &query=QUERY_TEXT_OR_URL

2. Syntax for Requesting Triples

   http://localhost:8080/fedora/risearch?type=triples
                                        &flush=[true (default is false)]
                                        &lang=SPO|iTQL
                                        &format=N-Triples|Notation 3|RDF/XML|Turtle
                                        &limit=[1 or more (default is no limit)]
                                        &distinct=[on (default is off)]
                                        &stream=[on (default is off)]
                                        &query=QUERY_TEXT_OR_URL
                                        &template=[TEMPLATE_TEXT_OR_URL (if applicable)]