From 6317fc1185eee20275994592cc82861266fdf703 Mon Sep 17 00:00:00 2001 From: Dominik Moritz Date: Sat, 6 Oct 2012 23:11:06 +0100 Subject: [PATCH] Make docs more readable --- doc/datastore.rst | 60 ++++++++++++++++++++++++----------------------- 1 file changed, 31 insertions(+), 29 deletions(-) diff --git a/doc/datastore.rst b/doc/datastore.rst index 0191e860b48..b956210a137 100644 --- a/doc/datastore.rst +++ b/doc/datastore.rst @@ -99,12 +99,12 @@ datastore_create The datastore_create API endpoint allows a user to post JSON data to be stored against a resource. This endpoint also supports altering tables, aliases and indexes and bulk insertion. The JSON must be in the following form:: { - resource_id: resource_id, # the data is going to be stored against. - aliases: # list of names for read only aliases to the resource - fields: [] # a list of dictionaries of fields/columns and their extra metadata. - records: [] # a list of dictionaries of the data, eg: [{"dob": "2005", "some_stuff": ['a', 'b']}, ..] - primary_key: # list of fields that represent a unique key - indexes: # indexes on table + resource_id: # the data is going to be stored against. + aliases: # list of names for read only aliases to the resource + fields: # a list of dictionaries of fields/columns and their extra metadata. + records: # a list of dictionaries of the data, eg: [{"dob": "2005", "some_stuff": ['a', 'b']}, ..] + primary_key: # list of fields that represent a unique key + indexes: # indexes on table } See :ref:`fields` and :ref:`records` for details on how to lay out records. @@ -117,10 +117,10 @@ datastore_delete The datastore_delete API endpoint allows a user to delete records from a resource. The JSON for searching must be in the following form:: { - resource_id: resource_id # the data that is going to be deleted. - filter: # dictionary of matching conditions to delete - # e.g {'key1': 'a', 'key2': 'b'} - # this will be equivalent to "delete from table where key1 = 'a' and key2 = 'b' " + resource_id: # the data that is going to be deleted. + filter: # dictionary of matching conditions to delete + # e.g {'key1': 'a', 'key2': 'b'} + # this will be equivalent to "delete from table where key1 = 'a' and key2 = 'b' " } @@ -131,10 +131,10 @@ The datastore_upsert API endpoint allows a user to add or edit records in an exi The JSON for searching must be in the following form:: { - resource_id: resource_id # resource id that the data is going to be stored under. - records: [] # a list of dictionaries of the data, eg: [{"dob": "2005", "some_stuff": ['a', 'b']}, ..] - method: # the method to use to put the data into the datastore - # possible options: upsert (default), insert, update + resource_id: # resource id that the data is going to be stored under. + records: # a list of dictionaries of the data, eg: [{"dob": "2005", "some_stuff": ['a', 'b']}, ..] + method: # the method to use to put the data into the datastore + # possible options: upsert (default), insert, update } ``upsert`` @@ -153,16 +153,16 @@ The datastore_search API endpoint allows a user to search data in a resource. The JSON for searching must be in the following form:: { - resource_id: # the resource id to be searched against - filters : # dictionary of matching conditions to select e.g {'key1': 'a. 'key2': 'b'} - # this will be equivalent to "select * from table where key1 = 'a' and key2 = 'b' " - q: # full text query - plain: # treat as plain text query (default: true) - language: # language of the full text query (default: english) - limit: # limit the amount of rows to size (default: 100) - offset: # offset the amount of rows - fields: # list of fields return in that order, defaults (empty or not present) to all fields in fields order. - sort: # ordered list of field names as, eg: "fieldname1, fieldname2 desc" + resource_id: # the resource id to be searched against + filters : # dictionary of matching conditions to select e.g {'key1': 'a. 'key2': 'b'} + # this will be equivalent to "select * from table where key1 = 'a' and key2 = 'b' " + q: # full text query + plain: # treat as plain text query (default: true) + language: # language of the full text query (default: english) + limit: # limit the amount of rows to size (default: 100) + offset: # offset the amount of rows + fields: # list of fields return in that order, defaults (empty or not present) to all fields in fields order. + sort: # ordered list of field names as, eg: "fieldname1, fieldname2 desc" } .. _datastore_search_sql: @@ -173,7 +173,7 @@ datastore_search_sql The datastore_search_sql API endpoint allows a user to search data in a resource or connect multiple resources with join expressions. The underlying SQL engine is the `PostgreSQL engine `_. The JSON for searching must be in the following form:: { - sql: # a single sql select statement + sql: # a single sql select statement } @@ -187,7 +187,7 @@ datastore_search_htsql The datastore_search_htsql API endpoint allows a user to search data in a resource using the `HTSQL `_ query expression language. The JSON for searching must be in the following form:: { - htsql: # a htsql query statement. + htsql: # a htsql query statement. } .. _fields: @@ -198,8 +198,8 @@ Fields Fields define the column names and the type of the data in a column. A field is defined as follows:: { - "id": # a string which defines the column name - "type": # the data type for the column + "id": # a string which defines the column name + "type": # the data type for the column } Field **types are optional** and will be guessed by the DataStore from the provided data. However, setting the types ensures that future inserts will not fail because of wrong types. See :ref:`valid-types` for details on which types are valid. @@ -225,7 +225,7 @@ Records A record is the data to be inserted in a table and is defined as follows:: { - "": # data to be set + "": # data to be set # .. more data } @@ -248,6 +248,8 @@ Field types The DataStore supports all types supported by PostgreSQL as well as a few additions. A list of the PostgreSQL types can be found in the `type section of the documentation`_. Below you can find a list of the most common data types. The ``json`` type has been added as a storage for nested data. +In addition to the listed types below, you can also use array types. They are defines by prepending a ``_`` or appending ``[]`` or ``[n]`` where n denotes the length of the array. An arbitrarily long array of integers would be defined as ``int[]``. + .. _type section of the documentation: http://www.postgresql.org/docs/9.1/static/datatype.html