--- /dev/null
+# Document Indexes\r
+\r
+## Overview\r
+An index can be thought of as a collection of _Documents_, and represents the largest granularity of data grouping in the store.\r
+\r
+The first step in persisting documents via the _Search Data Service_ is to create the _Index_ into which we will put the documents.\r
+\r
+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
+\r
+## Syntax\r
+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
+\r
+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
+ \r
+ {\r
+ "name": {"type": "string" },\r
+ "data-type": {"type": "string" },\r
+ "format": {"type": "string" },\r
+ "searchable": {"type": "boolean"},\r
+ "search-analyzer": {"type": "string" },\r
+ "index-analyzer": {"type": "string" }\r
+ }\r
+ \r
+Where,\r
+\r
+ name = An arbitrary label to assign to the _Index_\r
+ data-type = One of: string, date, long, double, boolean, ip, or nested*\r
+ format = For 'date' type fields, the date format string to use when persisting the field.\r
+ searchable = true - field will be indexed,\r
+ false - field will not be indexed\r
+ search-analyzer = Default analyzer to use for queries if one is not specified as part of the query\r
+ One of: whitespace or ngram.\r
+ index-analyser = Analyzer to use for this field when indexing documents being persisted to the Index\r
+ One of: whitespace or ngram.\r
+ \r
+\* **Nested** fields:\r
+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
+\r
+**Example - A simple document definition which includes a 'date' type field.**\r
+\r
+_Take note of the following:_\r
+* For our 'BirthDate' field, which is a date, we also specify the format string to use when storing the field's contents.\r
+\r
+ {\r
+ "fields": [\r
+ {"name": "FirstName", "data-type": "string"},\r
+ {"name": "LastName", "data-type": "string"},\r
+ {"name": "BirthDate", "data-type": "date", "format": "MMM d y HH:m:s"}\r
+ ]\r
+ }\r
+\r
+\r
+**Example - An example document definition containing nested sub-fields.**\r
+ \r
+_Take note of the following:_\r
+* It is perfectly valid for a nested field to itself contain nested fields\r
+* For the _Tracks.Title_ field, we are specifying that the _whitespace_ analyzer should be applied for both indexing and queries. \r
+\r
+ {\r
+ "fields": [\r
+ {"name": "Album", "data-type": "string"},\r
+ {"name": "Group", "data-type": "string"},\r
+ {"name": "Tracks", "data-type": "nested", "sub-fields": [\r
+ {"name": "Title", "data-type": "string", "index-analyzer": "whitespace", "search-analyzer": "whitespace"},\r
+ {"name": "Length", "data-type": "long"}\r
+ ]},\r
+ {"name": "BandMembers", "data-type": "nested", "sub-fields": [\r
+ {"name": "FirstName", "data-type": "string"},\r
+ {"name": "LastName", "data-type": "string"},\r
+ {"name": "Address", "data-type": "nested", "sub-fields": [\r
+ {"name": "Street", "data-type": "string"},\r
+ {"name": "City", "data-type": "string"},\r
+ {"name": "Country", "data-type": "string"}\r
+ ]}\r
+ ]}\r
+ ]\r
+ }\r
+## API\r
+\r
+### Create Index\r
+Define a new _Index_ in the _Search Data Service_.\r
+\r
+---\r
+**URL**\r
+\r
+ https://{host}:9509/services/search-data-service/v1/search/indexes/{index}/\r
+\r
+**Method** \r
+\r
+ PUT\r
+\r
+**URL Params**\r
+\r
+ index - The name to assign to the document index we are creating.\r
+\r
+**Request Header**\r
+\r
+ Accept = application/json\r
+ X-TransactionId = Unique id set by client (for logging purposes)\r
+ X-FromAppId = Application identifier (for logging purposes)\r
+ Content-Type = application/json\r
+ \r
+**Request Payload**\r
+\r
+ JSON format document structure for this index (see Syntax Section)\r
+\r
+**Success Response**\r
+\r
+ Code: 201\r
+ Header(s): None\r
+ Body: JSON structure containing the URL for the created Index \r
+ Example:\r
+ {"url": "indexes/myindex"}\r
+ \r
+**Error Response**\r
+\r
+ 400 - Bad Request\r
+ 403 - Unauthorized\r
+ 500 - Internal Error\r
+\r
+---\r
+\r
+\r
+### Delete Index\r
+Remove an existing _Index_ from the _Search Data Service_. \r
+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
+\r
+---\r
+**URL**\r
+\r
+ https://{host}:9509/services/search-data-service/v1/search/indexes/{index}/\r
+\r
+**Method** \r
+\r
+ DELETE\r
+\r
+**URL Params**\r
+\r
+ index - The name to assign to the document index we are creating.\r
+\r
+**Request Header**\r
+\r
+ Accept = application/json\r
+ X-TransactionId = Unique id set by client (for logging purposes)\r
+ X-FromAppId = Application identifier (for logging purposes)\r
+ Content-Type = application/json\r
+\r
+**Request Payload**\r
+\r
+ None\r
+\r
+**Success Response**\r
+\r
+ Code: 201\r
+ Header(s): None\r
+ Body: JSON structure containing the URL for the created Index \r
+ Example:\r
+ {"url": "indexes/myindex"}\r
+ \r
+**Error Response**\r
+\r
+ 400 - Bad Request\r
+ 403 - Unauthorized\r
+ 500 - Internal Error\r
+\r
+---\r
Code Review / aai / search-data-service.git / blobdiff