README.md

   1 # Search Engine Micro Service
   2
   3 The _Search Engine_ micro service exposes APIs via REST which allow clients to interact with the search database back end without requiring direct knowledge of or interaction with the underlying technology.
   4
   5 ## High Level Concepts
   6 This section establishes some of the terminology and concepts that relate to interacting with the _Search Engine_ service.
   7 A much more detailed examination of these concepts can be found on the  [Search Engine Design Share](http://d2athenaconf:8090/confluence/display/AAI/AAI-4633%3A+Search+DB+Abstraction%3A+Expose+REST+Interface) Confluence page.
   8
   9 ### Documents
  10 _Documents_ are the _things_ that we want to put into our document store.  At its most basic, a _document_ is a collection of _fields_ which contain the data that we want to be able to store and query.
  11
  12 _Fields_ are defined as having a name, a type, and optional parameters indicating whether or not the field is intended to be searchable, and if so, how it should be indexed.
  13
  14 ### Indexes
  15 An _index_ is essentially a collection of _documents_.  It is the top-level container into which we will store our documents.  A single data store may have multiple _indexes_ for the purposes of segregating different types of data (most queries are performed across all documents within  *single* instance).
  16
  17 ---
  18 ## Getting Started
  19
  20 ### Building The Micro Service
  21
  22 After checking out the project, execute the following Maven command from the project's top level directory:
  23
  24     > mvn clean install
  25
  26 ### Running The Micro Service Locally
  27 To run the microservice in your local environment, execute the following Maven command from the project's top level directory:
  28
  29     > mvn -P runAjsc
  30
  31 ### Running The Micro Service Within An Eclipse Environment
  32 It is often extremely useful to be able to run a micro service from within Eclipse in order to set breakpoints and perform general debugging activities.
  33
  34 For a good reference on how to launch any of the D2 micro services from within an Eclipse environment, refer to the following Confluence page: [Running An AJSC Container Within Eclipse](http://d2athenaconf:8090/confluence/pages/viewpage.action?pageId=1840887#DevelopingMicroserviceswithAT&T-RunninganAJSCContainerwithinEclipse)
  35
  36 ---
  37
  38 ## Public Interfaces
  39
  40 ### Echo Service
  41 The _Search Database Abstraction_ micro service supports the standard echo service to allow it to be 'pinged' to verify that the service is up and responding.
  42
  43 The echo service is reachable via the following REST end point:
  44
  45     http://{host}:9509/services/search-data-service/v1/jaxrsExample/jaxrs-services/echo/{input}
  46
  47 ### Indexes
  48 The _Search Engine_ service supports simple creation and deletion of document indexes via the following REST API calls:
  49
  50 ##### Create Index
  51     Method         : POST
  52     URL            : https://<host>:9509/services/search-data-service/v1/search/indexes/<index>/
  53     URL Params     : index - The name of the index to be created.
  54     Request Payload:
  55         A document structure expressed as json.
  56
  57     Response Payload:
  58         {"url": "< resource location of the index >"
  59
  60 ##### Delete Index
  61     Method         : DELETE
  62     URL            : http://<host>:9509/services/search-data-service/v1/search/indexes/<index>/
  63     URL Params     : index - The name of the index to be deleted.
  64     Request Payload:
  65         None
  66
  67
  68 ### Documents
  69
  70 ##### Create Document Without Specifying a Document Identifier
  71 Documents can be created via a POST request with no document identifier specified.  In this case the document store will generate an identifier to associate with the document.
  72
  73     Method         : POST
  74     URL            : https://<host>:9509/services/search-data-service/v1/search/indexes/<index>/documents/
  75     URL Params     : index       - The name of the index to create the document in.
  76     Request Payload:
  77         Document contents expressed as a JSON object containing key/value pairs.
  78
  79     Response Payload:
  80         { "etag": "string", "url": "string" }
  81
  82 ##### Create or Update Document With a Specified Document Identifier
  83 Documents can also be created via a PUT request which includes an identifier to associate with the document.  The put endpoint is actually used for both creates and updates, where this is distinguished as follows:
  84 * If the request header DOES NOT include a value in the If-Match field, then the request is assumed to be a document create.
  85 * If the request header DOES contain a value in the If-Match field, then the request is assumed to be a document update.
  86
  87     Method         : PUT
  88     URL            : https://<host>:9509/services/search-data-service/v1/search/indexes/<index>/documents<document id>
  89     URL Params     : index       - The name of the index to create or update the document in.
  90                      document id - The identifier of the document to be created or updated.
  91     Request Payload:
  92         Document contents expressed as a JSON object containing key/value pairs.
  93
  94     Response Payload:
  95         { "etag": "string", "url": "string"}
  96
  97 ##### Delete a Document
  98
  99     Method:        : DELETE
 100     URL            : https://<host>:9509/services/search-data-service/v1/search/indexes/<index>/documents<document id>
 101     URL Params     : index       - The name of the index to remove the document from.
 102                      document id - the identifier of the document to be deleted.
 103     Request Payload:
 104         None.
 105
 106 ##### Retrieve a Document
 107
 108     Method:        : GET
 109     URL            : https://<host>:9509/services/search-data-service/v1/search/indexes/<index>/documents<document id>
 110     URL Params     : index       - The name of the index to retrieve the document from.
 111                      document id - the identifier of the document to be retrieved.
 112     Request Payload:
 113         None.
 114
 115
 116 ### Searching the Document Store
 117 Search statements are passed to the _Search Data Service_ as a JSON object which is structured as follows:
 118
 119 _Filters_
 120 * A "filter" stanza defines a set of queries to be run in _non-scoring-mode_ to reduce the document set to a smaller subset to be searched.
 121 * The filter stanza is optional - omitting it implies that the query is _unfiltered_.
 122 * This stanza is represented as a JSON object with the following structure:
 123
 124     "filter": {
 125                 "all": [ { query }, { query },....{ query }],
 126                 "any": [ { query }, { query },....{ query }]
 127     },
 128
 129 Where:
 130 * the _all_ list defines a set of queryies such that ALL queries in the list must be satisfied for the document to pass the filter.
 131 * the _any_ list defines a set of queryies such that ANY single query in the list must be satisfied for the document to pass the filter.
 132
 133 _Queries_
 134 The following types of query statements are supported by the _Search Data Service_:
 135
 136 _Term Query_:
 137
 138 A term query attempts to match the literal value of a field, with no advanced parsing or analysis of the query string.  This type of query is most appropriate for structured data like numbers, dates and enums, rather than full text fields.
 139
 140      // Find documents where the specified field contains the supplied value
 141     "match": {
 142         "field": "value"
 143     }
 144
 145     // Find documents where the specified field DOES NOT contain the supplied value
 146     "not-match": {
 147         "field": "value"
 148     }
 149
 150 _Parsed Query_:
 151
 152 Parsed queries apply a query parser to the supplied query string in order to determine the exact query to apply to the specified field.
 153 The query string is parsed into a series of terms and operators, as described below:
 154
 155 Terms may be any of the following:
 156 * single words
 157 * exact phrases, as denoted by enclosing the phrase in open and close quotations.  Example: "this is my exact phrase"
 158 * regular expressions, as denoted by wrapping the expressing in forward slash ( / ) character.  Example: /joh?n(ath[oa]n)/
 159
 160 The supported operators are as follows:
 161 * AND - Both terms to the left or right of the operator MUST be present
 162 * OR  - Either the term to the left or right of the operator MUST be present
 163 * NOT - The term to the right of the operator MUST NOT be present.
 164
 165     "parsed-query": {
 166         "field": "fieldname",
 167         "query-string": "string"
 168     }
 169
 170 _Range Query_:
 171
 172  Range queries match fields whose term value falls within the specified numeric or date range.
 173  Supported bounds operators include:
 174  * gt  - Greater than
 175  * gte - Greater than or equal to
 176  * lt  - Less than
 177  * lte - Less than or equal to
 178
 179      "range": {
 180         "field": "fieldname",
 181         "operator": "value",
 182         "operator": "value"
 183      }
 184
 185 ##### Examples
 186 The following snippet illustrates a search statement describing a filtered query which uses examples of all of the supported query types:
 187
 188     {
 189         "filter": {
 190             "all": [{"range": {"field": "timestamp", "lte": "2016-12-01T00:00:00.558+03:00"}}],
 191             "any": [ ]
 192         },
 193
 194         "queries": [
 195             {"match": {"field": "name", "value": "Bob"}},
 196             {"parsed-query": {"field": "street-name", "query-string": "Main OR First"}},
 197             {"range": {"field": "street-number", "gt": 10, "lt": 50}}
 198         ]
 199     }
 200
 201 ##### REST Endpoint
 202
 203     Method:        : POST
 204     URL            : https://<host>:9509/services/search-data-service/v1/search/indexes/<index>/query
 205     URL Params     : index       - The name of the index to apply the query to.
 206
 207     Request Payload:
 208         {
 209             "filter": {
 210                 "all": [ { query }, { query },....{ query }],
 211                 "any": [ { query }, { query },....{ query }]
 212             },
 213
 214             "queries": [
 215                 { query },
 216                     .
 217                     .
 218                 { query }
 219             ]
 220         }
 221
 222 ### Bulk Operations
 223 Bulk operations allow the client to bundle a number of actions into a single REST request.
 224 It is important to note that individual operations bundled into a bulk request are considered by the _Search Service_ to be completely independent operations.  This has a few important consequences:
 225 * No guarantees are made with respect to the order in which the individual operations will be processed by the document store.
 226 * There is no implied transactionality between the operations.  Individual operations my succeed or fail independently of one another, and it is entirely possible for the client to receive back a result set indicating a mix of success and failure results for the individual operations.
 227
 228 ##### Submit Bulk Request
 229     Method        : POST
 230     URL           : http://<host>:9509/services/search-data-service/v1/search/bulk/
 231     URL Params    : NONE
 232     Request Payload:
 233         A json structure containing all of the bundled actions to be performed.
 234         It must correspond to the following format:
 235             [
 236                 { "operation": {{<metaData>}, {<document>},
 237                 { "operation": {{<metaData>}, {<document>},
 238                             .
 239                             .
 240                 { "operation": {{<metaData>}, {<document>},
 241             ]
 242
 243         Where,
 244             operation - Is one of:  "create", "update", or "delete"
 245
 246             metaData  - A structure containing meta-data associated with the individual operation to be performed.  Valid fields include:
 247                 "url"   - The resource identifier of the document to be operated on.
 248                 "etag" - Identifies the version of the document to be acted on.  Required for "update" and "delete" operations.
 249
 250             document - The document contents for "create" and "update" operations.
 251
 252         Example Payload:
 253         [
 254             {"create": {"metaData": {"url": "/services/search-data-service/v1/indexes/the-index/documents/1"}, "document": {"f1": "v1", "f2": "v2"}}},
 255             {"create": {"metaData": {"url": "/services/search-data-service/indexes/the-index/documents/2"}, "document": {"f1": "v1", "f2": "v2"}}},
 256             {"update": {"metaData": {"url": "/services/search-data-service/v1/search/indexes/the-index/documents/8", "etag": "1"}, "document": {"f1": "v1a", "f2": "v2a"}}},
 257             {"delete": {"metaData": {"url": "/services/search-data-service/v1/search/indexes/the-index/documents/99", "etag": "3"}}}
 258         ]
 259
 260     Response Payload:
 261         The response body will contain an aggregation of the collective results as well as separate status codes for each of the operations in the request.
 262         Example:
 263         {
 264             "total_operations": 4,
 265             "total_success": 1,
 266             "total_fails": 3,
 267                         "results": [
 268                                 {"operation": "create", "url": "/services/search-data-service/v1/search/indexes/the-index/documents/1", "etag": "1", "status-code": "201", "status-message": "OK"},
 269                                 {"operation": "create", "url": "/services/search-data-service/v1/search/indexes/the-index/documents/2", "etag": "1", "status-code": "201", "status-message": "OK"},
 270                                 {"operation": "update", "url": "/services/search-data-service/v1/search/indexes/the-index/documents/8", "etag": "2", "status-code": "200", "status-message": "OK"},
 271                                 {"operation": "delete", "url": "/services/search-data-service/v1/search/indexes/the-index/documents/2", "status-code": "200", "status-message": "OK"}
 272     ]
 273 }