INDEXES.md

   1 # Document Indexes\r
   2 \r
   3 ## Overview\r
   4 An index can be thought of as a collection of _Documents_, and represents the largest granularity of data grouping in the store.\r
   5 \r
   6 The first step in persisting documents via the _Search Data Service_ is to create the _Index_ into which we will put the documents.\r
   7 \r
   8 This is where we define the structure of the _Documents_ that we will be storing in our _Index_, including how we want the data in our documents to be analyzed and indexed so that they can be queried for in interesting and useful ways.\r
   9 \r
  10 ## Syntax\r
  11 When we create an _Index_ we need to define the structure of the _Documents_ that we will be storing in it.  Specifically, we must enumerate the _Fields_ that make up the _Document_, the type of data we expect to be stored in each _Field_, and how we want that data to be indexed by the back end document store.\r
  12 \r
  13 We express this as a JSON structure, enumerating the _Fields_ in our document, where each _Field_ is expressed as a JSON object which conforms to the following schema:\r
  14  \r
  15     {\r
  16         "name":            {"type": "string" },\r
  17         "data-type":       {"type": "string" },\r
  18         "format":          {"type": "string" },\r
  19         "searchable":      {"type": "boolean"},\r
  20         "search-analyzer": {"type": "string" },\r
  21         "index-analyzer":  {"type": "string" }\r
  22     }\r
  23     \r
  24 Where,\r
  25 \r
  26     name            = An arbitrary label to assign to the _Index_\r
  27     data-type       = One of:  string, date, long, double, boolean, ip, or nested*\r
  28     format          = For 'date' type fields, the date format string to use when persisting the field.\r
  29     searchable      = true  - field will be indexed,\r
  30                       false - field will not be indexed\r
  31     search-analyzer = Default analyzer to use for queries if one is not specified as part of the query\r
  32                       One of:  whitespace or ngram.\r
  33     index-analyser  = Analyzer to use for this field when indexing documents being persisted to the Index\r
  34                       One of:  whitespace or ngram.\r
  35                     \r
  36 \* **Nested** fields:\r
  37 If the _data-type_ is specified as _nested_, then this indicates that the contents of the field is itself a set of document fields.  In this case, the _Field_ definition should contain an additional entry named _sub-fields_, which is a JSON array containing the definitions of the sub-fields.  \r
  38 \r
  39 **Example - A simple document definition which includes a 'date' type field.**\r
  40 \r
  41 _Take note of the following:_\r
  42 * For our 'BirthDate' field, which is a date, we also specify the format string to use when storing the field's contents.\r
  43 \r
  44     {\r
  45         "fields": [\r
  46                 {"name": "FirstName", "data-type": "string"},\r
  47                 {"name": "LastName", "data-type": "string"},\r
  48                 {"name": "BirthDate", "data-type": "date", "format": "MMM d y HH:m:s"}\r
  49         ]\r
  50     }\r
  51 \r
  52 \r
  53 **Example - An example document definition containing nested sub-fields.**\r
  54   \r
  55 _Take note of the following:_\r
  56 * It is perfectly valid for a nested field to itself contain nested fields\r
  57 * For the _Tracks.Title_ field, we are specifying that the _whitespace_ analyzer should be applied for both indexing and queries. \r
  58 \r
  59     {\r
  60         "fields": [\r
  61                 {"name": "Album", "data-type": "string"},\r
  62                 {"name": "Group", "data-type": "string"},\r
  63                 {"name": "Tracks", "data-type": "nested", "sub-fields": [\r
  64                         {"name": "Title", "data-type": "string", "index-analyzer": "whitespace", "search-analyzer": "whitespace"},\r
  65                         {"name": "Length", "data-type": "long"}\r
  66                 ]},\r
  67                 {"name": "BandMembers", "data-type": "nested", "sub-fields": [\r
  68                         {"name": "FirstName", "data-type": "string"},\r
  69                         {"name": "LastName", "data-type": "string"},\r
  70                         {"name": "Address", "data-type": "nested", "sub-fields": [\r
  71                                 {"name": "Street", "data-type": "string"},\r
  72                                 {"name": "City", "data-type": "string"},\r
  73                                 {"name": "Country", "data-type": "string"}\r
  74                         ]}\r
  75                 ]}\r
  76         ]\r
  77     }\r
  78 ## API\r
  79 \r
  80 ### Create Index\r
  81 Define a new _Index_ in the _Search Data Service_.\r
  82 \r
  83 ---\r
  84 **URL**\r
  85 \r
  86     https://{host}:9509/services/search-data-service/v1/search/indexes/{index}/\r
  87 \r
  88 **Method** \r
  89 \r
  90     PUT\r
  91 \r
  92 **URL Params**\r
  93 \r
  94     index - The name to assign to the document index we are creating.\r
  95 \r
  96 **Request Header**\r
  97 \r
  98     Accept          = application/json\r
  99     X-TransactionId = Unique id set by client (for logging purposes)\r
 100     X-FromAppId     = Application identifier (for logging purposes)\r
 101     Content-Type    = application/json\r
 102     \r
 103 **Request Payload**\r
 104 \r
 105     JSON format document structure for this index (see Syntax Section)\r
 106 \r
 107 **Success Response**\r
 108 \r
 109     Code:      201\r
 110     Header(s): None\r
 111     Body:      JSON structure containing the URL for the created Index  \r
 112                Example:\r
 113                      {"url": "indexes/myindex"}\r
 114     \r
 115 **Error Response**\r
 116 \r
 117     400 - Bad Request\r
 118     403 - Unauthorized\r
 119     500 - Internal Error\r
 120 \r
 121 ---\r
 122 \r
 123 \r
 124 ### Delete Index\r
 125 Remove an existing _Index_ from the _Search Data Service_.  \r
 126 Note that this results in the removal of all _Documents_ that are stored in the _Index_ at the time that the DELETE operation occurs.\r
 127 \r
 128 ---\r
 129 **URL**\r
 130 \r
 131     https://{host}:9509/services/search-data-service/v1/search/indexes/{index}/\r
 132 \r
 133 **Method** \r
 134 \r
 135     DELETE\r
 136 \r
 137 **URL Params**\r
 138 \r
 139     index - The name to assign to the document index we are creating.\r
 140 \r
 141 **Request Header**\r
 142 \r
 143     Accept          = application/json\r
 144     X-TransactionId = Unique id set by client (for logging purposes)\r
 145     X-FromAppId     = Application identifier (for logging purposes)\r
 146     Content-Type    = application/json\r
 147 \r
 148 **Request Payload**\r
 149 \r
 150     None\r
 151 \r
 152 **Success Response**\r
 153 \r
 154     Code:      201\r
 155     Header(s): None\r
 156     Body:      JSON structure containing the URL for the created Index  \r
 157                Example:\r
 158                      {"url": "indexes/myindex"}\r
 159     \r
 160 **Error Response**\r
 161 \r
 162     400 - Bad Request\r
 163     403 - Unauthorized\r
 164     500 - Internal Error\r
 165 \r
 166 ---\r