Package org.sindice.siren.qparser.json

A JSON query parser implemented with Jackson and the Lucene's Flexible Query Parser.

See: Description

Class Summary

Class	Description
JsonQueryParser	This class is a helper that enables users to easily use the SIREn's JSON query parser.

Exception Summary

Exception	Description
ParseException	Exception thrown by the JsonQueryParser if an error occurs during parsing.

Package org.sindice.siren.qparser.json Description

A JSON query parser implemented with Jackson and the Lucene's Flexible Query Parser.

Query Parser Syntax

A JSON Query is composed of one top-level object, which can be either:

• a node (node) object that represents a NodeBooleanQuery or a NodePrimitiveQuery; or
• a twig (twig) object that represents a TwigQuery; or
• a boolean (boolean) object that represents a BooleanQuery of node and twig query objects.

The node and twig query object is composed of node boolean query expressions. A node boolean query expression must follow the syntax supported by the KeywordQueryParser. Examples of appropriately formatted keyword queries can be found in the keyword query syntax documentation.

Node

A node object is always prefixed by the field name "node" and follows the schema:

   "node" : {

     "query" : String,    // Node boolean query expression - Mandatory

     "level" : int,       // Node level constraint - Optional

     "range" : [int, int] // Node range constraint - Optional

   }
 

Twig

A twig object is always prefixed by the field name "twig" and follows the schema:

   "twig" : {

     "root"  : String,         // Node boolean query expression - Optional

     "level" : int,            // Node level constraint - Optional

     "range" : [int, int]      // Node range constraint - Optional

     "child" : [ Clause ]      // Array of child clauses - Optional

     "descendant" : [ Clause ] // Array of descendant clauses - Optional

   }
 

Boolean

A boolean object is always prefixed by the field name "boolean" and follows the schema:

   "boolean" : [ Clause ] // Array of clauses - Mandatory
 

Clause

A clause object follows the schema:

   {

     "occur" : String,   // Boolean operator (MUST, MUST_NOT, SHOULD) - Mandatory

     // With either a node object
     "node"  : { ... },  // Node object - Mandatory

     // Or a twig object
     "twig" : { ... },   // Twig object - Mandatory

     // A level field is mandatory only for descendant clauses
     "level" : int

   }
 

Query Examples

Node query

Match all the documents with one node containing the phrase "Marie Antoinette"

 {
   "node" : {
     "query" : "\"Marie Antoinette\""
   }
 }
 

Twig query

Match all the documents with one node containing the term "genre" and with a child node containing the term "Drama".

 {
   "twig" : {
     "root" : "genre",
     "child" : [ {
       "occur" : "MUST",
       "node" : {
         "query" : "Drama"
       }
     } ]
   }
 }
 

Such a twig query is the basic building block to query to a particular field name of a JSON object. The field name is always the root of the twig query and the field value is defined as a child clause.

More complex twig queries can be constructed by using nested twig queries or using more than one child (or descendant) clause.

 {
   "twig" : {
     "root" : "director",
     "child" : [ {
       "occur" : "MUST",
       "twig" : {
         "child" : [ {
           "occur" : "MUST",
           "twig" : {
             "root" : "last_name",
             "child" : [ {
               "occur" : "MUST",
               "node" : {
                 "query" : "Eastwood"
               }
             } ]
           }
         }, {
           "occur" : "MUST",
           "twig" : {
             "root" : "first_name",
             "child" : [ {
               "occur" : "MUST",
               "node" : {
                 "query" : "Clint"
               }
             } ]
           }
         } ]
       }
     } ]
   }
 }
 

Boolean Query

Node and twig queries can be combined freely using the boolean query object to create a boolean combination of node and twig queries.

 {
   "boolean" : [ {
     "occur" : "MUST",
     "twig" : {
       "root" : "genre",
       "child" : [ {
         "occur" : "MUST",
         "node" : {
           "query" : "Drama"
         }
       } ]
     }
   }, {
     "occur" : "MUST",
     "twig" : {
       "root" : "year",
       "child" : [ {
         "occur" : "MUST",
         "node" : {
           "query" : "2010"
         }
       } ]
     }
   } ]
 }
 

Query Builder DSL

The package provides also a simple query builder to easily create JSON queries programmatically. See QueryBuilder.