You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@usergrid.apache.org by sn...@apache.org on 2015/08/05 16:56:36 UTC
[50/51] [abbrv] [partial] incubator-usergrid git commit: Switch over
to new docs for the website.
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/2a55601f/content/docs/_sources/data-queries/query-language.txt
----------------------------------------------------------------------
diff --git a/content/docs/_sources/data-queries/query-language.txt b/content/docs/_sources/data-queries/query-language.txt
new file mode 100644
index 0000000..a491740
--- /dev/null
+++ b/content/docs/_sources/data-queries/query-language.txt
@@ -0,0 +1,427 @@
+# Query Language
+
+> Query examples in this content are shown unencoded to make
+> them easier to read. Keep in mind that you might need to encode query
+> strings if you're sending them as part of URLs, such as when you're
+> executing them with the cURL tool.
+
+The following example retrieves a list of restaurants (from a
+restaurants collection) whose name property contains the value "diner",
+sorting the list in ascending order by name:
+
+ /restaurants?ql=select * where name contains 'diner' order by name asc
+
+
+## Basic syntax
+
+Queries of Usergrid data for Apache Usergrid are made up of two kinds of
+statements: the path to the collection you want to query, followed by
+the query language statement containing your query. These two statements
+are separated by "?ql=" to indicate where the query language statement
+starts.
+
+To retrieve items from a collection, you would use a syntax such as the
+following:
+
+ /<collection>?ql=<query_statement>
+
+In the following example, the query is retrieving all users whose name
+is Gladys Kravitz.
+
+ /users?ql=select * where name = 'Gladys Kravitz'
+
+The following example selects all items except those that have an a
+property value of 5:
+
+ /items?ql=select * where NOT a = 5
+
+Note that there is a shortcut available when your query selects all
+items matching certain criteria -- in other words, where you use a
+statement that starts "select \* where". In this case, you can omit the
+first part of the statement and abbreviate it this way:
+
+ /items?ql=NOT a = 5
+
+You query your Apache Usergrid data by using a query syntax that's like
+Structured Query Language (SQL), the query language for relational
+databases. Unlike a relational database, where you specify tables and
+columns containing the data you want to query, in your Apache Usergrid
+queries you specify collections and entities.
+
+The syntax of Apache Usergrid queries only *resembles* SQL to
+make queries familiar and easier to write. However, the language isn't
+SQL. Only the syntax items documented here are supported.
+
+## Supported operators
+
+Comparisons
+
+* Less than `<` or `lt`
+* Less than or equal `<=` or `lte`
+* Equal `=` or `eq`
+* Greater than or equal `>=` or `gte`
+* Greater than `>` or `gt`
+* Not equal `NOT`
+
+Logical operations
+
+* Intersection of results `and`
+* Union of results `or`
+* Subtraction of results `not`
+
+
+## Query Response Format
+
+the query’s response is formatted in
+JavaScript Object Notation (JSON). This is a common format used for
+parameter and return values in REST web services.
+
+So for the following query:
+
+ /users?ql=select * where name = ‘Gladys Kravitz’
+
+...you would get a response such as the the one below. The JSON format
+arranges the data in name/value pairs. Many of the values correspond to
+specifics of the request, including the request’s HTTP action (GET), the
+application’s UUID, the request’s parameters (the query string you
+sent), and so on.
+
+Here, the query is asking for whole entities in the users collection.
+Data corresponding to the response is captured in the response’s
+`entities` array. The array has one member here, corresponding to the
+one user found by the query (another kind of query might have found more
+users). That one member gives the UUID of the entity (user), the entity
+type, and values for properties such as name, username, email, and so
+on.
+
+```json
+{
+ "action" : "get",
+ "application" : "8272c9b0-d86a-11e2-92e2-cdf1ce04c1c0",
+ "params" : {
+ "ql" : [ "select * where name = 'Gladys Kravitz'" ]
+ },
+ "path" : "/users",
+ "uri" : "http://api.usergrid.com/myorg/myapp/users",
+ "entities" : [ {
+ "uuid" : "d0d7d0ba-e97b-11e2-8cef-411c466c4f2c",
+ "type" : "user",
+ "name" : "Gladys Kravitz",
+ "created" : 1373472876859,
+ "modified" : 1373472876859,
+ "username" : "gladys",
+ "email" : "gladys@example.com",
+ "activated" : true,
+ "picture" : "http://www.gravatar.com/avatar/20c57d4f41cf51f2db44165eb058b3b2",
+ "metadata" : {
+ "path" : "/users/d0d7d0ba-e97b-11e2-8cef-411c466c4f2c",
+ "sets" : {
+ "rolenames" : "/users/d0d7d0ba-e97b-11e2-8cef-411c466c4f2c/rolenames",
+ "permissions" : "/users/d0d7d0ba-e97b-11e2-8cef-411c466c4f2c/permissions"
+ },
+ "connections" : {
+ "firstname" : "/users/d0d7d0ba-e97b-11e2-8cef-411c466c4f2c/firstname",
+ "lastname" : "/users/d0d7d0ba-e97b-11e2-8cef-411c466c4f2c/lastname"
+ },
+ "collections" : {
+ "activities" : "/users/d0d7d0ba-e97b-11e2-8cef-411c466c4f2c/activities",
+ "devices" : "/users/d0d7d0ba-e97b-11e2-8cef-411c466c4f2c/devices",
+ "feed" : "/users/d0d7d0ba-e97b-11e2-8cef-411c466c4f2c/feed",
+ "groups" : "/users/d0d7d0ba-e97b-11e2-8cef-411c466c4f2c/groups",
+ "roles" : "/users/d0d7d0ba-e97b-11e2-8cef-411c466c4f2c/roles",
+ "following" : "/users/d0d7d0ba-e97b-11e2-8cef-411c466c4f2c/following",
+ "followers" : "/users/d0d7d0ba-e97b-11e2-8cef-411c466c4f2c/followers"
+ }
+ }
+ } ],
+ "timestamp" : 1374694196061,
+ "duration" : 48,
+ "organization" : "myorg",
+ "applicationName" : "myapp",
+ "count" : 1
+}
+```
+
+Compare the preceding example with the following for another kind of
+query. Imagine the following request string, where the query string is
+asking for only the values of two of the entity’s properties (username
+and name):
+
+ /users?ql=select username,name where name=’Gladys Kravitz’
+
+In the response JSON from this query, the return value is specified as
+the property of the `list` item -- here, an array containing only the
+values of the properties the query asked for, in the order they were
+requested (username first, then name).
+
+ {
+ "action" : "get",
+ "application" : "8272c9b0-d86a-11e2-92e2-cdf1ce04c1c0",
+ "params" : {
+ "ql" : [ "select username,name where name='Gladys Kravitz'" ]
+ },
+ "path" : "/users",
+ "uri" : "http://api.usergrid.com/myorg/myapp/users",
+ "list" : [ [ "gladys", "Gladys Kravitz" ] ],
+ "timestamp" : 1374697463190,
+ "duration" : 25,
+ "organization" : "myorg",
+ "applicationName" : "myapp",
+ "count" : 1
+ }
+
+
+## Data types supported in queries
+
+As you develop queries for your Apache Usergrid data, remember that entity
+properties each conform to a particular data type (whether the entity is
+included by default or an entity you defined). Your queries must
+acknowledge this, testing with values that conform to each property's
+data type. (You can view the list of property data types for the default
+entities at [Default Data Entities](/default-data-entities).)
+
+For example, in the default entity `User`, the `name` property is stored
+as a `string`, the created date as a `long`, and metadata is stored as a
+JSON object. Your queries must be data type-aware so that you can be
+sure that query results are as you expect them to be.
+
+So imagine you define an entity with a `price` property whose value
+might be `100.00`. Querying for `100` will return no results even if
+there are occurrences of `100.00` as `price` values in your data set.
+That's because the database expected a decimal-delimited `float` value
+in your query.
+
+
+Data Type Examples Notes
+----------- ------------------------------------------------------------------------------------------- ---------
+`string` `'value'`, `unicode '\uFFFF'`, `octal '\0707'` true | false
+`long` 1357412326021 Timestamps are typically stored as `long` values.
+`float` 10.1, -10.1, 10e10, 10e-10, 10E10, 10e-10 Your query must be specific about the value you're looking for, down to the value (if any) after the decimal point.
+`boolean` true | false
+`UUID` ee912c4b-5769-11e2-924d-02e81ac5a17b UUID types are typically used for the unique IDs of entities. The value must conform to the following format (do not enclose with quotation marks): xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+
+
+`object` For a JSON object like this one:
+
+```
+ {
+ "items":[
+ {"name":"rocks"},
+ {"name":"boats"}
+ ]
+ }
+```
+
+you can use dot notation to reach property values in the object: /mycollection/thing?ql="select * where items.name = 'rocks'" Objects are often used to contain entity metadata, such as the activities associated with a user, the users associated with a role, and so on.
+
+## Retrieving values for multiple properties
+
+Your query can return multiple kinds of values -- such as the values of
+multiple properties -- by specifying the property names in your select
+statement as a comma-separated list.
+
+For example, the following request returns the address and phone number
+of users whose name is Gladys Kravitz:
+
+ /users?ql=select address,phone_number where name = 'Gladys Kravitz'
+
+
+## Querying for the contents of text
+
+Your query can search the text of entity values of the string data type.
+For example, you can search a postal code field for values that start
+with a specific three numbers.
+
+For example, the following query selects all restaurants with the word
+`diner` in the name:
+
+ /restaurants?ql=select * where name contains 'diner'
+
+**Note:** Not all string properties of the default entities are
+indexed for searching. This includes the `User` entity's `username`
+property.
+
+This will return all users whose name property contains the word 'Kravitz'
+
+ /users?ql=select * where name contains 'Kravitz'
+
+This will return all users whose name property contains a word beginning with 'Krav'
+
+ /users?ql=select * where name contains 'Krav*'
+
+This will return all users whose name is exactly 'Gladys Kravitz'
+
+ /users?ql=select * where name = 'Gladys Kravitz'
+
+
+## Sorting results
+
+You can return query results that are sorted in the order you specify.
+Use the `order by` clause to specify the property to sort by, along with
+the order in which results should be sorted. The syntax for the clause
+is as follows `order by <property_name> asc | desc`
+
+The following table includes a few examples:
+
+ /users?ql=select * where lastname = 'Smith' order by firstname asc
+
+
+ /users?ql=select * where lastname = 'Smith' order by firstname desc
+
+
+ /users?ql=select * where lastname contains 'Sm*' order by lastname asc, firstname asc
+
+
+## Geoqueries
+
+Many of today's apps are enhanced by the use of *geolocation*, wireless
+detection of the physical location of a remote device. These apps are
+said to be *geolocation-aware* in that they query the device to
+determine the user's position and then use this data to further enhance
+the user's experience. For example, apps can capture the exact location
+where a picture was taken or a message was created.
+
+Usergrid support geolocation on any entity, both built in (e.g.,
+users, groups) and user defined.
+
+To add a location to any entity, include the following member to the
+JSON in a POST or PUT call:
+
+ "location": {
+ "latitude": 37.779632,
+ "longitude": -122.395131
+ }
+
+For example, to store a listing of restaurants and their locations,
+start by creating a collection called restaurants:
+
+ POST https://api.usergrid.com/org_name/app_name/restaurants
+
+Next, add a new entity to the collection:
+
+ POST https://api.usergrid.com/org_name/app_name/restaurants
+ {
+ "name": "Rockadero",
+ "address": "21 Slate Street, Bedrock, CA",
+ "location": {
+ "latitude": 37.779632,
+ "longitude": -122.395131
+ }
+ }
+
+This creates a new restaurant entity called "Rockadero" with the
+longitude and latitude included as part of the object.
+
+When a location is added to an entity, it is easy to make queries
+against that data. For example, to see all restaurants within a 10 mile
+radius of the user's location, make a GET call against that entity, and
+include a search query in the following format:
+
+ location within <distance in meters> of <latitude>, <longitude>
+
+If we use the location of our user Fred, we first need to convert miles
+to meters. 1 mile is equivalent to 1609.344 meters, so 10 miles is about
+16093 meters. Thus, the API call looks like this:
+
+ GET https://api.usergrid.com/org_name/app_name/restaurants?ql=location within 16093 of 37.776753, -122.407846
+
+
+## Managing large sets of results
+
+When your query might return more results than you want to display to
+the user at once, you can use the limit parameter with cursors or API
+methods to manage the display of results. By default, query results are
+limited to 10 at a time. You can adjust this by setting the limit
+parameter to a value you prefer.
+
+For example, you might execute a query that could potentially return
+hundreds of results, but you want to display 20 of those at a time to
+users. To do this, your code sets the limit parameter to 20 when
+querying for data, then provides a way for the user to request more of
+the results when they're ready.
+
+You would use the following parameters in your query:
+
++-------------------------+-------------------------+-------------------------+
+| Parameter | Type | Description |
++=========================+=========================+=========================+
+| `limit` | integer | Number of results to |
+| | | return. The maximum |
+| | | number of results is |
+| | | 1,000. Specifying a |
+| | | limit greater than |
+| | | 1,000 will result in a |
+| | | limit of 1,000. |
+| | | |
+| | | Limit is applied to the |
+| | | collection, not the |
+| | | query string. For |
+| | | example, the following |
+| | | query will find the |
+| | | first 100 entities in |
+| | | the books collection, |
+| | | then from that set |
+| | | return the ones with |
+| | | author='Hemingway': |
+| | | |
+| | | /books?ql=author = |
+| | | 'Hemingway'&limit=100 |
+| | | |
+| | | You can also use the |
+| | | limit parameter on a |
+| | | request without a query |
+| | | string. The following |
+| | | example is shorthand |
+| | | for selecting all books |
+| | | and limiting by 100 at |
+| | | a time: |
+| | | |
+| | | /books?limit=100 |
+| | | |
+| | | Using a limit on a |
+| | | DELETE can help you |
+| | | manage the amount of |
+| | | time it takes to delete |
+| | | data. For example you |
+| | | can delete all of the |
+| | | books, 1000 at a time, |
+| | | with the following: |
+| | | |
+| | | DELETE /books?limit |
+| | | =1000 |
+| | | |
+| | | Keep in mind that |
+| | | DELETE operations can |
+| | | take longer to execute. |
+| | | Yet even though the |
+| | | DELETE query call might |
+| | | time out (such as with |
+| | | a very large limit), |
+| | | the operation will |
+| | | continue on the server |
+| | | even if the client |
+| | | stops waiting for the |
+| | | result. |
++-------------------------+-------------------------+-------------------------+
+| `cursor` | string | An encoded |
+| | | representation of the |
+| | | query position pointing |
+| | | to a set of results. To |
+| | | retrieve the next set |
+| | | of results, pass the |
+| | | cursor with your next |
+| | | call for most results. |
++-------------------------+-------------------------+-------------------------+
+
+For example:
+
+Select all users whose name starts with fred, and returns the first 50
+results:
+
+ /users?ql=select * where name = 'fred*'&limit=50
+
+Retrieve the next batch of users whose name is "fred", passing the
+cursor received from the last request to specify where the next set of
+results should begin:
+
+ /users?ql=select * where name = 'fred*'&limit=50&cursor=LTIxNDg0NDUxNDpnR2tBQVFFQWdITUFDWFJ2YlM1emJXbDBhQUNBZFFBUUQyMVZneExfRWVLRlV3TG9Hc1doZXdDQWRRQVFIYVdjb0JwREVlS1VCd0xvR3NWT0JRQQ
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/2a55601f/content/docs/_sources/data-queries/query-parameters.txt
----------------------------------------------------------------------
diff --git a/content/docs/_sources/data-queries/query-parameters.txt b/content/docs/_sources/data-queries/query-parameters.txt
new file mode 100644
index 0000000..9f9fc68
--- /dev/null
+++ b/content/docs/_sources/data-queries/query-parameters.txt
@@ -0,0 +1,153 @@
+# Query parameters & clauses
+
+When querying your data, you can use your query string to get the data, then sort and manage it on the client. This topic describes a few techniques.
+
+Query examples in this content are shown unencoded to make them easier to read. Keep in mind that you might need to encode query strings if you're sending them as part of URLs, such as when you're executing them with the cURL tool.
+
+<div class="admonition note"> <p class="first admonition-title">Note</p> <p class="last">
+Optimizing queries. As a best practice, you should include no more than 3 parameters in your queries. The API will not prevent you from submitting a query with more than 3 parameters; however, due to the nature of NoSQL, queries with many parameters can quickly become very inefficient.
+</p></div>
+
+For more information, see our [Usergrid DBMS overview](../data-store/data-storage-dbms.html) and [Data store best practices](../data-storage/optimizing-access).
+
+### Contains
+
+Your query can search the text of entity values of the string data type. For example, you can search a postal code field for values that start with a specific three numbers.
+
+For example, the following query selects all restaurants with the word diner in the name:
+
+ /restaurants?ql=select * where restaurants contains 'diner'
+
+__Note__: Not all string properties of the default entities are indexed for searching. This includes the User entity's username property.
+
+The following table lists a few examples of the kind of searches you can do in queries.
+
+<table class="usergrid-table">
+ <tr>
+ <td>Goal</td>
+ <td>Example</td>
+ <td>Notes</td>
+ </tr>
+ <tr>
+ <td>Find books whose 'title' property contains the full word "tale".</td>
+ <td><pre>/books?ql=select * where title contains 'tale'</pre></td>
+ <td>containslooks for the occurrence of a full word anywhere in the searched property. Note that contains will not work on the 'name' property, since it is not full-text indexed in the database.</td>
+ </tr>
+ <tr>
+ <td>Find books whose 'title' property contains a word that starts with "ta".</td>
+ <td><pre>/books?ql=select * where title contains 'ta*'</pre></td>
+ <td>containswill look for partial words if you include a wildcard.</td>
+ </tr>
+ <tr>
+ <td>Find books whose title property is exactly and only "A Tale of Two Cities".</td>
+ <td><pre>/books?ql=select * where title = 'A Tale of Two Cities'</pre></td>
+ <td>The = operator is looking for a match in the entire searched property value. Use a * wildcard to look for some set of the first characters only.</td>
+ </tr>
+</table>
+
+
+### Location
+
+If you've stored location data with your entities, you can query for the proximity of the geographical locations those entities represent. For more information on geolocation, see Geolocation.
+
+<table class="usergrid-table">
+ <tr>
+ <td>Goal</td>
+ <td>Example</td>
+ <td>Notes</td>
+ </tr>
+ <tr>
+ <td>Find stores whose locations are within the specified longitude and latitude.</td>
+ <td><pre>/stores?ql=location within 500 of 40.042016, -86.900749</pre></td>
+ <td>within will test for values within the value you specify. The within value is expressed as a number of meters.<br>The return results are sorted in order of nearest to furthest. If there are multiple entries at the same location, they're returned in the order they were added to the database.<br> For more on geolocation queries, see Geolocation.</td>
+ </tr>
+</table>
+
+### Order by
+
+You can return query results that are sorted in the order you specify. Use the order by clause to specify the property to sort by, along with the order in which results should be sorted. The syntax for the clause is as follows:
+
+ order by <property_name> asc | desc
+
+The following table includes a few examples:
+
+<table class="usergrid-table">
+ <tr>
+ <td>Goal</td>
+ <td>Example</td>
+ </tr>
+ <tr>
+ <td>Sort by first name in ascending order</td>
+ <td>/users?ql=select * where lastname = 'Smith' order by firstname asc</td>
+ </tr>
+ <tr>
+ <td>Sort by first name in descending order</td>
+ <td>/users?ql=select * where lastname = 'Smith' order by firstname desc</td>
+ </tr>
+ <tr>
+ <td>Sort by last name, then first name in ascending orderl</td>
+ <td>/users?ql=select * where lastname contains 'Sm*' order by lastname asc, firstname asc</td>
+ </tr>
+<table>
+
+
+### Limit
+
+When your query might return more results than you want to display to the user at once, you can use the limit parameter with cursors or API methods to manage the display of results. By default, query results are limited to 10 at a time. You can adjust this by setting the limit parameter to a value you prefer.
+
+For example, you might execute a query that could potentially return hundreds of results, but you want to display 20 of those at a time to users. To do this, your code sets the limit parameter to 20 when querying for data, then provides a way for the user to request more of the results when they're ready.
+
+You would use the following parameters in your query:
+
+<table class="usergrid-table">
+ <tr>
+ <td>Parameter</td>
+ <td>Type</td>
+ <td>Description</td>
+ </tr>
+ <tr>
+ <td>limit</td>
+ <td>integer</td>
+ <td><p>Number of results to return. The maximum number of results is 1,000.
+ Specifying a limit greater than 1,000 will result in a limit of 1,000.</p>
+ <p>You can also use the limit parameter on a request without a query string.
+ The following example is shorthand for selecting all books and limiting by 100 at a time:</p>
+ <pre>/books?limit=100</pre>
+ <p>Using a limit on a DELETE can help you manage the amount of time it takes
+ to delete data. For example you can delete all of the books, 1000 at a time,
+ with the following:</p>
+ <pre>DELETE /books?limit=1000</pre>
+ <p> Keep in mind that DELETE operations can take longer to execute.
+ Yet even though the DELETE query call might time out (such as with a
+ very large limit), the operation will continue on the server even if
+ the client stops waiting for the result.</p>
+ </td>
+ </tr>
+</table>
+
+For example:
+
+Select all users whose name starts with fred, and returns the first 50 results:
+
+ /users?ql=select * where name = 'fred*'&limit=50
+
+
+### Cursor
+
+<table class="usergrid-table">
+ <tr>
+ <td>Parameter</td>
+ <td>Type</td>
+ <td>Description</td>
+ </tr>
+ <tr>
+ <td>cursor</td>
+ <td>string</td>
+ <td>An encoded representation of the query position pointing to a set of results. To retrieve the next set of results, pass the cursor with your next call for most results./td>
+ </tr>
+</table>
+
+Retrieve the next batch of users whose name is "fred", passing the cursor received from the last request to specify where the next set of results should begin:
+
+ /users?ql=select * where name = 'fred*'&limit=50&cursor=LTIxNDg0NDUxNDpVdjb0JwREVlS1VCd0xvR3NWT0JRQQ
+
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/2a55601f/content/docs/_sources/data-queries/querying-your-data.txt
----------------------------------------------------------------------
diff --git a/content/docs/_sources/data-queries/querying-your-data.txt b/content/docs/_sources/data-queries/querying-your-data.txt
new file mode 100644
index 0000000..fa10169
--- /dev/null
+++ b/content/docs/_sources/data-queries/querying-your-data.txt
@@ -0,0 +1,121 @@
+# Querying your data
+
+This article describes how to use queries to filter data retrieved from your backend data store. Queries allow you to work with only the data you need, making your app more efficient and manageable by reducing the number of entities returned or acted on by the API. A query can be sent with any GET, PUT or DELETE request. For example, you might query the API to retrieve only the user entities with the property status:'active' to get a list of your users that have active accounts.
+
+For information on more advanced query usage and syntax, see [Query parameters & clauses](query-parameters.html).
+
+<div class="admonition note"> <p class="first admonition-title">Note</p> <p class="last">
+Query examples in this content are shown unencoded to make them easier to read. Keep in mind that you might need to encode query strings if you're sending them as part of URLs, such as when you're executing them with the cURL tool.
+</p></div>
+
+## Basic query usage
+
+The following examples show how to query the Usergrid API to return the first 5 entities in the users collection that contain the property status:'active'.
+
+<div class="admonition note"> <p class="first admonition-title">Note</p> <p class="last">
+Optimizing queries: As a best practice, you should include no more than 3 parameters in your queries. The API will not prevent you from submitting a query with more than 3 parameters; however, due to the nature of NoSQL, queries with many parameters can quickly become very inefficient.
+</p></div>
+
+For more information, see our [Usergrid DBMS overview](../data-store/data-storage-dbms.html) and [Data store best practices](../data-storage/optimizing-access).
+
+### Request Syntax
+
+ https://api.usergrid.com/<org>/<app>/<collection>?ql=<query_statement>
+
+Note: Any values specified in the query statement should be enclosed in single-quotes.
+
+ https://api.usergrid.com/your-org/your-app/users?limit=5&ql=select * where status = 'active'
+
+Alternatively, when you use a statement that starts select * where you can omit the first part of the statement and abbreviate it this way:
+
+ https://api.usergrid.com/your-org/your-app/users?limit=5&ql=status = 'active'
+
+### Retrieving values for multiple properties
+
+Your query can return multiple kinds of values -- such as the values of multiple properties -- by specifying the property names in your select statement as a comma-separated list.
+
+For example, the following request returns the address and phone number of users whose name is Gladys Kravitz:
+
+ /users?ql=select address,phone_number where name = 'Gladys Kravitz'
+
+### Response syntax
+
+When you query your data, the API response is formatted in JavaScript Object Notation (JSON). This is a common format used for parameter and return values in REST web services.
+
+Data corresponding to the response is captured in the response’s entities array. The array will include one JSON-object for each entity returned for the query. Each returned entity will include a number of default properties, including the UUID of the entity, the entity type, and values for properties such as name, username, email, and so on. For a complete list of default properties by entity type, see Default Data Entity Types.
+
+For example, the following query for all entities of type user where the name property equals 'Gladys Kravitz':
+
+ /users?ql=select * where name = ‘Gladys Kravitz’
+
+will return the following response:
+
+ {
+ "action" : "get",
+ "application" : "8272c9b0-d86a-11e2-92e2-cdf1ce04c1c0",
+ "params" : {
+ "ql" : [ "select * where name = 'Gladys Kravitz'" ]
+ },
+ "path" : "/users",
+ "uri" : "http://api.usergrid.com/myorg/myapp/users",
+ "entities" : [ {
+ "uuid" : "d0d7d0ba-e97b-11e2-8cef-411c466c4f2c",
+ "type" : "user",
+ "name" : "Gladys Kravitz",
+ "created" : 1373472876859,
+ "modified" : 1373472876859,
+ "username" : "gladys",
+ "email" : "gladys@example.com",
+ "activated" : true,
+ "picture" : "http://www.gravatar.com/avatar/20c57d4f41cf51f2db44165eb058b3b2",
+ "metadata" : {
+ "path" : "/users/d0d7d0ba-e97b-11e2-8cef-411c466c4f2c",
+ "sets" : {
+ "rolenames" : "/users/d0d7d0ba-e97b-11e2-8cef-411c466c4f2c/rolenames",
+ "permissions" : "/users/d0d7d0ba-e97b-11e2-8cef-411c466c4f2c/permissions"
+ },
+ "connections" : {
+ "firstname" : "/users/d0d7d0ba-e97b-11e2-8cef-411c466c4f2c/firstname",
+ "lastname" : "/users/d0d7d0ba-e97b-11e2-8cef-411c466c4f2c/lastname"
+ },
+ "collections" : {
+ "activities" : "/users/d0d7d0ba-e97b-11e2-8cef-411c466c4f2c/activities",
+ "users" : "/users/d0d7d0ba-e97b-11e2-8cef-411c466c4f2c/users",
+ "feed" : "/users/d0d7d0ba-e97b-11e2-8cef-411c466c4f2c/feed",
+ "groups" : "/users/d0d7d0ba-e97b-11e2-8cef-411c466c4f2c/groups",
+ "roles" : "/users/d0d7d0ba-e97b-11e2-8cef-411c466c4f2c/roles",
+ "following" : "/users/d0d7d0ba-e97b-11e2-8cef-411c466c4f2c/following",
+ "followers" : "/users/d0d7d0ba-e97b-11e2-8cef-411c466c4f2c/followers"
+ }
+ }
+ } ],
+ "timestamp" : 1374694196061,
+ "duration" : 48,
+ "organization" : "myorg",
+ "applicationName" : "myapp",
+ "count" : 1
+ }
+
+Compare the preceding example with the following for another kind of query. Imagine the following request string, where the query string is asking for only the values of two of the entity’s properties (username and name):
+
+ /users?ql=select username,name where name=’Gladys Kravitz’
+
+In the response JSON from this query, the return value is specified as the property of the list item -- here, an array containing only the values of the properties the query asked for, in the order they were requested (username first, then name).
+
+ {
+ "action" : "get",
+ "application" : "8272c9b0-d86a-11e2-92e2-cdf1ce04c1c0",
+ "params" : {
+ "ql" : [ "select username,name where name='Gladys Kravitz'" ]
+ },
+ "path" : "/users",
+ "uri" : "http://api.usergrid.com/myorg/myapp/users",
+ "list" : [ [ "gladys", "Gladys Kravitz" ] ],
+ "timestamp" : 1374697463190,
+ "duration" : 25,
+ "organization" : "myorg",
+ "applicationName" : "myapp",
+ "count" : 1
+ }
+
+
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/2a55601f/content/docs/_sources/data-storage/collections.txt
----------------------------------------------------------------------
diff --git a/content/docs/_sources/data-storage/collections.txt b/content/docs/_sources/data-storage/collections.txt
new file mode 100644
index 0000000..c072104
--- /dev/null
+++ b/content/docs/_sources/data-storage/collections.txt
@@ -0,0 +1,254 @@
+# Collections
+
+## Creating Collections
+
+This article describes how to create collections in Advanced Usergrid. All entities are automatically associated with a corresponding collection based on the type property of the entity. You may create empty collections if you wish, but creating an entity of a new type will automatically create a corresponding collection for you. For example, creating a new custom "item" entity, creates an "items" collection.
+
+__Note__: Although not shown in the API examples below, you need to provide a valid access token with each API call. See Authenticating users and application clients for details.
+
+### Creating a collection
+
+The following example shows how to create an empty collection. Alternatively, you can create a collection simply by creating a new entity with a 'type' property that corresponds to the collection you wish to create. For more on creating entities, see Creating Custom Data Entities
+
+### Request Syntax
+
+ curl -X POST https://api.usergrid.com/<org>/<app>/<collection_name>
+
+Parameters
+
+Parameter Description
+--------- -----------
+org Organization UUID or organization name
+app Application UUID or application name
+collection name Name of the collection to create.
+
+If the provided value is not a plural word, Usergrid will pluralize it. For example, providing 'item' will create a collection named 'items' but providing 'items' will not create 'itemses'.
+
+### Example Request/Response
+
+Request:
+
+ curl -X POST "https://api.usergrid.com/your-org/your-app/item"
+
+Response:
+
+ {
+ "action" : "post",
+ "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0",
+ "params" : { },
+ "path" : "/items",
+ "uri" : "http://api.usergrid.com/your-org/your-app/items",
+ "entities" : [ ],
+ "timestamp" : 1378857079220,
+ "duration" : 31,
+ "organization" : "your-org",
+ "applicationName" : "your-app"
+ }
+
+## Retrieving Collections
+
+This article describes how to retrieve all of the entities in a collection.
+
+<div class="admonition note"> <p class="first admonition-title">Note</p> <p class="last">
By default, the Usergrid API returns 10 entities per request. For collections with more than 10 entities, use the returned 'cursor' property to retrieve the next 10 entities in the result set. You may also use the LIMIT parameter in a query string to increase the number of results returned. For more information on using cursors, see [Query Parameters](../data-queries/query-parameters.html).</p></div>
+
+__Note__: Although not shown in the API examples below, you need to provide a valid access token with each API call. See Authenticating users and application clients for details.
+
+### Retrieving sets of entities from a collection
+
+### Request Syntax
+
+ curl -X GET https://api.usergrid.com/<org>/<app>/<collection>
+
+Parameters
+
+Parameter Description
+--------- -----------
+org Organization UUID or organization name
+app Application UUID or application name
+collection Collection UUID or collection name
+
+### Example Request/Response
+
+Request:
+
+ curl -X GET "https://api.usergrid.com/your-org/your-app/items"
+
+Response:
+
+ {
+ "action" : "get",
+ "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0",
+ "params" : { },
+ "path" : "/items",
+ "uri" : "http://api.usergrid.com/your-org/your-app/items",
+ "entities" : [ {
+ "uuid" : "5bb76bca-1657-11e3-903f-9ff6c621a7a4",
+ "type" : "item",
+ "name" : "milk",
+ "created" : 1378405020796,
+ "modified" : 1378405020796,
+ "metadata" : {
+ "path" : "/items/5bb76bca-1657-11e3-903f-9ff6c621a7a4"
+ },
+ "name" : "milk",
+ "price" : "3.25"
+ }, {
+ "uuid" : "1a9356ba-1682-11e3-a72a-81581bbaf055",
+ "type" : "item",
+ "name" : "bread",
+ "created" : 1378423379867,
+ "modified" : 1378423379867,
+ "metadata" : {
+ "path" : "/items/1a9356ba-1682-11e3-a72a-81581bbaf055"
+ },
+ "name" : "bread",
+ "price" : "2.50"
+ } ],
+ "timestamp" : 1378426821261,
+ "duration" : 35,
+ "organization" : "your-org",
+ "applicationName" : "your-app",
+ "count" : 2
+ }
+
+## Updating Collections
+
+This article describes how to perform batch updates on all entities in a collection. Batch updates require the use of a query string in the request, which can either specify all entities in the collection or a subset of entities for the update to be performed on. For more information on queries, see Querying your data.
+
+__Note__: Although not shown in the API examples below, you need to provide a valid access token with each API call. See Authenticating users and application clients for details.
+
+### Batch updating entities in a collection
+
+### Request Syntax
+
+ curl -X PUT https://api.usergrid.com/<org>/<app>/<collection>/?ql= -d {<property>}
+
+Note the empty query string (ql=) appended to the URL.
+
+Parameters
+
+Parameter Description
+--------- -----------
+org Organization UUID or organization name
+app Application UUID or application name
+collection Collection UUID or collection name property
+
+An entity property to be updated, formatted as a key-value pair. For example:
+
+ {"property_1":"value_1", "property_2":"value_2",...}
+
+### Example Request/Response
+
+Request:
+
+ curl -X PUT https://api.usergrid.com/your-org/your-app/items/?ql= -d '{"availability":"in-stock"}'
+
+Note the empty ?ql= query string.
+
+Response:
+
+ {
+ "action" : "put",
+ "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0",
+ "params" : {
+ "ql" : [ "" ]
+ },
+ "path" : "/items",
+ "uri" : "http://api.usergrid.com/your-org/your-app/items",
+ "entities" : [ {
+ "uuid" : "31847b9a-1a62-11e3-be04-8d05e96f700d",
+ "type" : "item",
+ "name" : "milk",
+ "price" : "3.25",
+ "availability" : "in-stock"
+ "created" : 1378849479113,
+ "modified" : 1378849567301,
+ "name" : "milk",
+ }, {
+ "uuid" : "3192ac6a-1a62-11e3-a24f-496ca1d42ce7",
+ "type" : "item",
+ "name" : "bread",
+ "price" : "4.00",
+ "availability" : "in-stock"
+ "created" : 1378849479206,
+ "modified" : 1378849567351,
+ "name" : "bread",
+ } ],
+ "timestamp" : 1378849567280,
+ "duration" : 207,
+ "organization" : "your-org",
+ "applicationName" : "your-app"
+ }
+
+## Deleting Collections
+This article describes how to batch delete entities in a collection. Batch deletes require the use of a query string in the request, which specifies a subset of entities to be deleted. For more information on queries, see Querying your data.
+
+Currently, collections cannot be deleted; however, you can delete all of the entities from a collection.
+
+__Note__: Although not shown in the API examples below, you need to provide a valid access token with each API call. See Authenticating users and application clients for details.
+
+### Batch deleting entities in a collection
+
+### Request Syntax
+
+ curl -X DELETE https://api.usergrid.com/<org>/<app>/<collection>/?ql=<query>
+
+Parameters
+
+Parameter Description
+--------- -----------
+org Organization UUID or organization name
+app Application UUID or application name
+collection Collection UUID or collection name
+query A query string that specifies the subset of entities to delete
+
+(for more information on queries, see Querying your data)
+
+### Example Request/Response
+
+The following example will delete the first 5 entities in a collection.
+
+Request:
+
+ curl -X DELETE https://api.usergrid.com/your-org/your-app/items/?ql="limit=5"
+
+Response:
+
+ {
+ "action" : "delete",
+ "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0",
+ "params" : {
+ "ql" : [ "" ]
+ },
+ "path" : "/items",
+ "uri" : "http://api.usergrid.com/your-org/your-app/items",
+ "entities" : [ {
+ "uuid" : "53fe3700-0abe-11e3-b1f7-1bd100b8059e",
+ "type" : "item",
+ "name" : "milk",
+ "price" : "3.25",
+ "created" : 1377129832047,
+ "modified" : 1377129832047,
+ "metadata" : {
+ "path" : "/items/53fe3700-0abe-11e3-b1f7-1bd100b8059e"
+ },
+ "name" : "milk"
+ }, {
+ "uuid" : "5ae1fa7a-0abe-11e3-89ab-6be0003c809b",
+ "type" : "item",
+ "name" : "bread",
+ "price" : "4.00",
+ "created" : 1377129843607,
+ "modified" : 1377129843607,
+ "metadata" : {
+ "path" : "/items/5ae1fa7a-0abe-11e3-89ab-6be0003c809b"
+ },
+ "name" : "bread"
+ } ],
+ "timestamp" : 1378848117272,
+ "duration" : 12275,
+ "organization" : "your-org",
+ "applicationName" : "your-app"
+ }
+
+
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/2a55601f/content/docs/_sources/data-storage/data-store-dbms.txt
----------------------------------------------------------------------
diff --git a/content/docs/_sources/data-storage/data-store-dbms.txt b/content/docs/_sources/data-storage/data-store-dbms.txt
new file mode 100644
index 0000000..539cca6
--- /dev/null
+++ b/content/docs/_sources/data-storage/data-store-dbms.txt
@@ -0,0 +1,109 @@
+# The Usergrid Data Store
+
+The Usergrid data store is backed by Cassandra, an open source distributed DBMS. Cassandra isn’t a relational database system (RDBMS), and is sometimes placed in the category of “NoSQL” or “schema-less” databases.
+
+<!-- workaround a Sphinx bug -->
+<div class="admonition note"> <p class="first admonition-title">Note</p> <p class="last">
+Usergrid is not a relational database. Optimizing for performance on a non-relational database like Cassandra differs a bit from relational databases. For more information, see Optimizing access to your Usergrid data store.</p> </div>
+
+
+Cassandra is specifically designed to support applications that need flexibility and high scalability, particularly web and mobile applications. Usergrid client applications write and read data formatted as JavaScript Object Notation (JSON). (Usergrid provides SDKs through which client apps can do much of this work in their native language. For more information, see Usergrid SDKs.)
+
+With Cassandra as the underlying DBMS, apps benefit from:
+
+Fast writes to the data store.
+* A distributed architecture that means no single point of failure.
+* Flexibility in data model design. You aren't constrained by a schema.
+* Linear scalability.
+
+If you have experience with relational databases and are unfamiliar with "NoSQL" databases, the following table might be a helpful start. It maps the high-level concepts of an RDBMS’s data model both to Cassandra’s and to the Usergrid, which is backed by Cassandra.
+
+<table class="usergrid-table">
+<tr>
+ <td></td>
+ <td>RDBMS</td>
+ <td>Cassandra</td>
+ <td>Usergrid</td>
+</tr>
+<tr>
+ <td>Each tuple is modeled as</td>
+ <td>A row.</td>
+ <td>A row.</td>
+ <td>An entity. Written and retrieved as JSON, an entity contains values for all of its properties in the way a row has values for columns.</td>
+</tr>
+<tr>
+ <td>Each data attribute is modeled as</td>
+ <td>A column.</td>
+ <td>A column. Many thousands of columns are supported.</td>
+ <td>A entity property. An entity has a default set of properties, including the entity’s UUID. You can add many more to support your application.</td>
+</tr>
+<tr>
+ <td>Each group of attributes is modeled as</td>
+ <td>A table.</td>
+ <td>A column family. Unlike rows in tables, rows in a column family can have differing numbers of columns. Because you’re not using a schema to define the model, you can update the column list for a row at any time.</td>
+ <td>An entity collection. As with its underlying Cassandra column family, a collection can have entities with differing numbers of properties. In other words, just because one entity has an authorId property doesn’t mean that other entities in its collection need to.</td>
+</tr>
+</table>
+
+The following examples from a product database provide simple illustrations of these differences.
+
+An RDBMS table has a schema-defined set of columns per row.
+
+.. image:: rdbms.png
+
+A Cassandra column family includes rows that can have differing column sets.
+
+.. image:: cassandra.png
+
+In the JSON from the Usergrid application, the products are represented as entities. Note that each entity in the entities array below has a slightly different set of properties, like the columns in a Cassandra column family.
+
+ {
+ "action" : "get",
+ "application" : "<app_uuid>",
+ "params" : {},
+ "path" : "/products",
+ "uri" : "https://api.usergrid.com/my_org/my_app/products",
+ "entities" : [ {
+ "uuid" : "<product_uuid>",
+ "type" : "product",
+ "created" : 1395410098517,
+ "modified" : 1395410098517,
+ "image" : "http://path.jpg",
+ "metadata" : {
+ "path" : "/products/<product_uuid>"
+ },
+ "name" : "Bouncy Castle",
+ "sku" : "35450349822"
+ },
+ {
+ "uuid" : "<product_uuid>",
+ "type" : "product",
+ "created" : 1395409669686,
+ "modified" : 1395409669686,
+ "image" : "http://path.jpg",
+ "metadata" : {
+ "path" : "/products/<product_uuid>"
+ },
+ "description" : "It makes coffee.",
+ "name" : "Coffee Maker",
+ "sku" : "60723023589"
+ },
+ {
+ "uuid" : "<product_uuid>",
+ "type" : "product",
+ "created" : 1395407700578,
+ "modified" : 1395407700578,
+ "metadata" : {
+ "path" : "/products/<product_uuid>"
+ },
+ "name" : "Air Mattress",
+ "sku" : "53045985365"
+ }],
+ "timestamp" : 1396290037640,
+ "duration" : 91,
+ "organization" : "my_org",
+ "applicationName" : "my_app",
+ "count" : 3
+ }
+
+
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/2a55601f/content/docs/_sources/data-storage/entities.txt
----------------------------------------------------------------------
diff --git a/content/docs/_sources/data-storage/entities.txt b/content/docs/_sources/data-storage/entities.txt
new file mode 100644
index 0000000..5a70b18
--- /dev/null
+++ b/content/docs/_sources/data-storage/entities.txt
@@ -0,0 +1,512 @@
+# Entities
+
+## Creating Custom Data Entities
+This article describes how to create custom data entities and entity properties. Entity types correspond to the name of collection to which they are posted. For example, if you create a new custom "dog" entity, a "dogs" collection will be created if one did not already exist. If a "dogs" collection already exists, the new "dog" entity will be saved in it. All user-defined properties are indexed, and strings that contain multiple words are keyword-indexed.
+
+The methods cited in this article should be used to create custom data entities. If you are using one of the Usergrid SDKs, use one of the entity type-specific SDK methods to create default data entities.
+
+__Note__: Although not shown in the API examples below, you need to provide a valid access token with each API call. See Authenticating users and application clients for details.
+
+### Creating a custom entity
+When a new entity is created, Usergrid will automatically create a corresponding collection if one does not already exist. The collection will automatically be named with the plural form of the entity type. For example, creating a custom entity of type 'item' will automatically create a collection named 'items' in which all future 'item' entities will be saved.
+
+### Request Syntax
+
+ curl -X POST https://api.usergrid.com/<org>/<app>/<entity_type> -d 'json_object'
+
+Parameters
+
+Parameter Description
+--------- -----------
+org Organization UUID or organization name
+app Application UUID or application name
+entity_type Entity type to create.
+json_object JSON representation of entity properties
+
+(For a full list of default properties, see Default Data Entity Types)
+
+Usergrid will create a corresponding collection if one does not already exist. To add an entity to an existing collections, use the pluralized collection name for entity_type.
+
+### Example Request/Response
+
+Request:
+
+ curl -X POST "https://api.usergrid.com/your-org/your-app/item" -d '{"name":"milk", "price":"3.25"}'
+
+Response:
+
+ {
+ "action" : "post",
+ "application" : "4a1edb70-d7a8-11e2-9ce3-f315e5aa568a",
+ "params" : { },
+ "path" : "/items", "uri" : "http://api.usergrid.com/my-org/my-app/items",
+ "entities" : [ {
+ "uuid" : "83e9b7ea-e8f5-11e2-84df-e94123890c7a",
+ "type" : "item",
+ "name" : "milk",
+ "created" : 1373415195230,
+ "modified" : 1373415195230,
+ "metadata" : {
+
+ "path" : "/items/83e9b7ea-e8f5-11e2-84df-e94123890c7a"
+ },
+ "name" : "milk",
+ "price" : "3.25"
+ } ],
+ "timestamp" : 1373415195225,
+ "duration" : 635,
+ "organization" : "my-org",
+ "applicationName" : "my-app"
+ }
+
+## Creating multiple custom entities
+
+### Request Syntax
+
+ curl -X POST https://api.usergrid.com/<org>/<app>/<entity_type>/ -d 'json_array'
+
+Parameters
+
+Parameter Description
+--------- -----------
+org Organization UUID or name
+app Application UUID or name
+entity_type Custom entity type to create.
+json_array JSON array of entities to be created.
+
+Usergrid will create a corresponding collection if one does not already exist. To add an entity to an existing collections, use the collection name or collection UUID in place of the entity type.
+
+### Example Request/Response
+
+Request:
+
+ curl -X POST "https://api.usergrid.com/your-org/your-app/item" -d '[{"name":"milk", "price":"3.25"}, {"name":"bread", "price":"2.50"}]'
+
+Response:
+
+ {
+ "action" : "post",
+ "application" : "f34f4222-a166-11e2-a7f7-02e9sjwsf3d0",
+ "params" : { },
+ "path" : "/items",
+ "uri" : "http://api.usergrid.com/your-org/your-app/items",
+ "entities" : [ {
+ "uuid" : "f3a8061a-ef0b-11e2-9e92-5f4a65c16193",
+ "type" : "item",
+ "name" : "milk",
+ "price" : "3.25",
+ "created" : 1374084538609,
+ "modified" : 1374084538609,
+ "metadata" : {
+ "path" : "/multis/f3a8061a-ef0b-11e2-9e92-5f4a65c16193"
+ },
+ "name" : "milk"
+ }, {
+ "uuid" : "f3be262a-ef0b-11e2-a51b-6715d5ef47a6",
+ "type" : "item",
+ "name" : "bread",
+ "price" : "2.50",
+ "created" : 1374084538754,
+ "modified" : 1374084538754,
+ "metadata" : {
+ "path" : "/items/f3be262a-ef0b-11e2-a51b-6715d5ef47a6"
+ },
+ "name" : "bread"
+ } ],
+ "timestamp" : 1374084538584,
+ "duration" : 388,
+ "organization" : "your-org",
+ "applicationName" : "your-app"
+ }
+
+### Creating an entity with sub-properties
+
+Any valid JSON object can be stored in an entity, regardless of the level of complexity, including sub-properties. For example, suppose you have an 'items' collection that contains an entity named 'milk'. You might store the different varieties of milk as sub-properties of a 'varieties' property:
+
+ {
+ "type" : "item"
+ "name" : "milk"
+ "varieties" : [ {
+ "name" : "1%",
+ "price" : "3.25",
+ "sku" : "0393847575533445"
+ }, {
+ "name" : "whole",
+ "price" : "3.85",
+ "sku" : "0393394956788445"
+ }, {
+ "name" : "skim",
+ "price" : "4.00",
+ "sku" : "0390299933488445"
+ } ]
+ }
+
+### Updating sub-properties
+
+An array of sub-properties is treated as a single object. This means that sub-properties cannot be updated atomically. All sub-properties of a given property must be updated as a set.
+For more on updating an existing sub-property, see Updating Data Entities.
+
+Example Request/Response
+
+ Request:
+ //Note the use of square brackets for specifying multiple nested objects
+ curl -X POST "https://api.usergrid.com/your-org/your-app/items" -d '{"varieties":[{"name":"1%","price" : "3.25", "sku" : "0393847575533445"},{"name" : "whole", "price" : "3.85", "sku" : "0393394956788445"}, {"name" : "skim", "price" : "4.00", "sku" : "0390299933488445"}]}'
+ Response:
+ {
+ "action" : "post",
+ "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0",
+ "params" : { },
+ "path" : "/items",
+ "uri" : "http://api.usergrid.com/your-org/your-app/items",
+ "entities" : [ {
+ "uuid" : "0d7cf92a-effb-11e2-917d-c5e707256e71",
+ "type" : "item",
+ "name" : "milk",
+ "created" : 1374187231666,
+ "modified" : 1374187231666,
+ "metadata" : {
+ "path" : "/items/0d7cf92a-effb-11e2-917d-c5e707256e71"
+ },
+ "name" : "milk",
+ "varieties" : [ {
+ "name" : "1%",
+ "price" : "3.25",
+ "SKU" : "0393847575533445"
+ }, {
+ "name" : "whole",
+ "price" : "3.85",
+ "SKU" : "0393394956788445"
+ }, {
+ "name" : "skim",
+ "price" : "4.00",
+ "SKU" : "0390299933488445"
+ } ]
+ } ],
+ "timestamp" : 1374187450826,
+ "duration" : 50,
+ "organization" : "your-org",
+ "applicationName" : "your-app"
+ }
+
+.. -----------------------------------------------------------------------------
+
+## Retrieving Data Entities
+This article describes how to retrieve entities from your account.
+
+__Note__: Although not shown in the API examples below, you need to provide a valid access token with each API call. See Authenticating users and application clients for details.
+
+With the exception of the user entity, all data entities can be retrieved by using their UUID or a 'name' property. The user entity can be retrieved by UUID or the 'username' property. The value for the 'name' or 'username' property must be unique.
+
+### Retrieving an entity
+
+### Request Syntax
+
+ curl -X GET https://api.usergrid.com/<org>/<app>/<collection>/<entity>
+
+Parameters
+
+Parameter Description
+--------- -----------
+org Organization UUID or organization name
+app Application UUID or application name
+collection Collection UUID or collection name
+entity Entity UUID or entity name
+
+### Example Request/Response
+
+Request:
+
+Retrieve by UUID:
+
+ curl -X GET "https://api.usergrid.com/your-org/your-app/items/da4a50dc-38dc-11e2-b2e4-02e81adcf3d0"
+
+Retrieve by 'name' property:
+
+ curl -X GET "https://api.usergrid.com/your-org/your-app/items/milk"
+
+Response:
+
+ {
+ "action" : "get",
+ "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0",
+ "params" : { },
+ "path" : "/items",
+ "uri" : "http://api.usergrid.com/amuramoto/sandbox/items",
+ "entities" : [ {
+ "uuid" : "5bb76bca-1657-11e3-903f-9ff6c621a7a4",
+ "type" : "item",
+ "name" : "milk",
+ "created" : 1378405020796,
+ "modified" : 1378405020796,
+ "metadata" : {
+ "path" : "/items/5bb76bca-1657-11e3-903f-9ff6c621a7a4"
+ },
+ "name" : "milk",
+ "price" : "3.25"
+ } ],
+ "timestamp" : 1378405025763,
+ "duration" : 31,
+ "organization" : "amuramoto",
+ "applicationName" : "sandbox"
+ }
+
+### Retrieving multiple entities
+
+This example describes how to retrieve multiple entities by UUID. You can also retrieve a set of entities by using a query string. For more information on querying your data, see Querying your data.
+
+### Request Syntax
+
+ curl -X GET https://api.usergrid.com/<org_id>/<app_id>/<collection>?ql= uuid = <entity_uuid> OR uuid = <entity_uuid>; ...
+
+Parameters
+
+Parameter Description
+--------- -----------
+org_id Organization UUID or organization name
+app_id Application UUID or application name
+collection Collection UUID or collection name
+query A url-encoded query string of entity properties to be matched.
+
+The query must be in Usergrid Query Language, for example:
+
+ ?ql=uuid="<entity_uuid>"" OR name="<entity_name>" OR...
+
+You may also specify the following for certain entity types:
+
+User entities: username = <entity_username>
+
+All other entities except groups: name = <entity_name>
+
+### Example Request/Response
+
+Request:
+
+ //note the url-encoded query string
+ curl -X GET "https://api.usergrid.com/your-org/your-app/items?ql=name%3D'milk'%20OR%20UUID%3D1a9356ba-1682-11e3-a72a-81581bbaf055&limit="
+
+Note: The query parameter of the request must be url encoded for curl requests
+
+Response:
+
+ {
+ "action" : "get",
+ "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0",
+ "params" : {
+ "ql" : [ "name='milk' OR UUID=1a9356ba-1682-11e3-a72a-81581bbaf055" ]
+ },
+ "path" : "/items",
+ "uri" : "http://api.usergrid.com/your-org/your-app/items",
+ "entities" : [ {
+ "uuid" : "5bb76bca-1657-11e3-903f-9ff6c621a7a4",
+ "type" : "item",
+ "name" : "milk",
+ "created" : 1378405020796,
+ "modified" : 1378405020796,
+ "metadata" : {
+ "path" : "/items/5bb76bca-1657-11e3-903f-9ff6c621a7a4"
+ },
+ "name" : "milk",
+ "price" : "3.25"
+ }, {
+ "uuid" : "1a9356ba-1682-11e3-a72a-81581bbaf055",
+ "type" : "item",
+ "name" : "bread",
+ "created" : 1378423379867,
+ "modified" : 1378423379867,
+ "metadata" : {
+ "path" : "/items/1a9356ba-1682-11e3-a72a-81581bbaf055"
+ },
+ "name" : "bread",
+ "price" : "2.50"
+ } ],
+ "timestamp" : 1378423793729,
+ "duration" : 63,
+ "organization" : "your-org",
+ "applicationName" : "your-app",
+ "count" : 2
+ }
+
+
+.. --------------------------------------------------------------------------------
+
+## Updating Data Entities
+
+This article describes how to update entities in your account.
+
+__Note__: Although not shown in the API examples below, you need to provide a valid access token with each API call. See Authenticating users and application clients for details.
+
+### Updating an entity
+One or more properties can be updated with a single PUT request. For information on updating sub-properties, see Updating sub-properties below.
+
+### Request Syntax
+
+ curl -X PUT https://api.usergrid.com/<org>/<app>/<collection>/<entity> -d {<property>}
+
+Parameters
+
+Parameter Description
+--------- -----------
+org_id Organization UUID or organization name
+app_id Application UUID or application name
+collection Name of the collection containing the entity to be updated
+uuid|name UUID or name of the data entity to be updated
+json_object JSON object with a field for each property to be updated
+
+An entity property to be updated, formatted as a key-value pair. For example:
+
+ {"property_1":"value_1", "property_2":"value_2",...}
+
+### Example Request/Response
+
+Request:
+
+ curl -X PUT https://api.usergrid.com/your-org/your-app/items/milk -d '{"price":"4.00", "availability":"in-stock"}'
+
+Response:
+
+ {
+ "action" : "put",
+ "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0",
+ "params" : { },
+ "path" : "/items",
+ "uri" : "http://api.usergrid.com/your-org/your-app/items",
+ "entities" : [ {
+ "uuid" : "5bb76bca-1657-11e3-903f-9ff6c621a7a4",
+ "type" : "item",
+ "name" : "milk",
+ "created" : 1378405020796,
+ "modified" : 1378505705077,
+ "availability" : "in-stock",
+ "metadata" : {
+ "path" : "/items/5bb76bca-1657-11e3-903f-9ff6c621a7a4"
+ },
+ "name" : "milk",
+ "price" : "4.00"
+ } ],
+ "timestamp" : 1378505705050,
+ "duration" : 87,
+ "organization" : "your-org",
+ "applicationName" : "your-app"
+ }
+
+
+### Updating a sub-property
+
+Data entities may contain sets of sub-properties as nested JSON objects. Unlike normal entity properties, however, sub-properties cannot be updated individually. Updating a nested object will cause all sub-properties within it to be overwritten.
+
+For example, if you have a data entity with the following nested object:
+
+### Request Syntax
+
+ curl -X PUT https://api.usergrid.com/<org_id>/<app_id>/<collection>/<uuid|name> -d '{<property> : [{<sub_property>}, {<sub_property>}...]}'
+
+Parameters
+
+Parameter Description
+--------- -----------
+org_id Organization UUID or organization name
+app_id Application UUID or application name
+collection Name of the collection containing the entity to be updated
+uuid|name UUID or name of the data entity to be updated
+json_object JSON object with a field for each property to be updated
+
+### Example Request/Response
+
+Request:
+
+ curl -X PUT https://api.usergrid.com/your-org/your-app/items/milk -d '{"varieties":[{"name":"1%","price":"3.25"},{"name":"whole","price":"4.00"}]}'
+
+Response:
+
+ {
+ "action" : "put",
+ "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0",
+ "params" : { },
+ "path" : "/items",
+ "uri" : "http://api.usergrid.com/your-org/your-app/items",
+ "entities" : [ {
+ "uuid" : "5bb76bca-1657-11e3-903f-9ff6c621a7a4",
+ "type" : "item",
+ "name" : "milk",
+ "created" : 1378405020796,
+ "modified" : 1378761459069,
+ "availability" : "in-stock",
+ "metadata" : {
+ "path" : "/items/5bb76bca-1657-11e3-903f-9ff6c621a7a4"
+ },
+ "name" : "milk",
+ "uri" : "http://api.usergrid.com/your-org/your-app/items/5bb76bca-1657-11e3-903f-9ff6c621a7a4",
+ "varieties" : [ {
+ "name" : "1%",
+ "price" : "3.25"
+ }, {
+ "name" : "whole",
+ "price" : "4.00"
+ } ]
+ } ],
+ "timestamp" : 1378761459047,
+ "duration" : 62,
+ "organization" : "your-org",
+ "applicationName" : "your-app"
+ }
+
+## Deleting Data Entities
+
+This article describes how to delete data entities.
+
+__Note__:Although not shown in the API examples below, you need to provide a valid access token with each API call. See Authenticating users and application clients for details.
+
+### Deleting an entity
+
+### Request Syntax
+
+ curl -X DELETE https://api.usergrid.com/<org>/<app>/<collection>/<entity>
+
+Parameters
+
+Parameter Description
+--------- -----------
+org Organization UUID or organization name
+app Application UUID or application name
+collection Collection UUID or collection name
+entity Entity UUID or entity name
+
+### Example Request/Response
+
+Request:
+
+Delete by UUID:
+
+ curl -X DELETE "https://api.usergrid.com/your-org/your-app/items/da4a50dc-38dc-11e2-b2e4-02e81adcf3d0"
+
+Delete by 'name' property:
+
+ curl -X DELETE "https://api.usergrid.com/your-org/your-app/items/milk"
+
+Response:
+
+ {
+ "action" : "delete",
+ "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0",
+ "params" : { },
+ "path" : "/items",
+ "uri" : "http://api.usergrid.com/your-org/your-app/items",
+ "entities" : [ {
+ "uuid" : "328fe64a-19a0-11e3-8a2a-ebc6f49d1fc4",
+ "type" : "item",
+ "name" : "milk",
+ "created" : 1378766158500,
+ "modified" : 1378766158500,
+ "metadata" : {
+ "path" : "/items/328fe64a-19a0-11e3-8a2a-ebc6f49d1fc4"
+ },
+ "name" : "milk",
+ "price" : "3.25"
+ } ],
+ "timestamp" : 1378766172016,
+ "duration" : 324,
+ "organization" : "your-org",
+ "applicationName" : "your-app"
+ }
+
+
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/2a55601f/content/docs/_sources/data-storage/optimizing-access.txt
----------------------------------------------------------------------
diff --git a/content/docs/_sources/data-storage/optimizing-access.txt b/content/docs/_sources/data-storage/optimizing-access.txt
new file mode 100644
index 0000000..2e5c0b6
--- /dev/null
+++ b/content/docs/_sources/data-storage/optimizing-access.txt
@@ -0,0 +1,185 @@
+# Data Store Best Practices
+The Usergrid data store is backed by Cassandra, an open source distributed DBMS. Cassandra is specifically designed to support applications that need flexibility and high scalability, particularly web and mobile applications. To get the most out of your Usergrid application, you should optimize your data access with this kind of database in mind.
+
+## Put your data in as you'll want to get it out
+The best practices described here are all related to the theme of putting your data in the way you’ll want to get it out. You’ll model your data with your likely read requests in mind rather than by modeling around the structure of the data itself (as you might with a relational database). In many cases, you can avoid using queries that are inefficient for this kind of database.
+
+You can use the following techniques to optimize data store access:
+
+* __Denormalize and duplicate__. By creating a data model that strategically denormalizes and duplicates data, you can avoid costly queries. In other words, you model the data so that all of the data for a given request is all in one place rather than scattered in a way that a query must account for.
+
+* __Create direct paths to the data you’ll want__. You can optimize your app’s performance by connecting entities your code retrieves most often. With connections, you can avoid some queries that might add complexity and reduce performance.
+
+## Best practice: Denormalize for pre-computed query results
+If you’re familiar with designing relational databases, you’re probably used to normalizing the structure of your data as much as possible. When normalizing an RDBMS data model, you minimize redundancy by ensuring that a column from one table is duplicated only once in any other table, and only when necessary to create primary/secondary key relationships. You then retrieve data that spans tables by joining them with an SQL query.
+
+In contrast, with the Usergrid data store you’ll get better performance by strategically denormalizing and duplicating data. When you denormalize, you combine data from what might (in a relational model) have been separate tables. When duplicating, you intentionally maintain copies of certain entity properties across multiple entities. By denormalizing and duplicating, you can collect the results of requests into a single entity rather than relying on a query.
+
+Part of designing your data model should include identifying the queries your client will make. Then in your data model design, you capture the results of those queries in advance by writing that data into entities of one collection you can read from later.
+
+### Getting review data the relational way
+For example, take a closer look at the relational case through a product database. Imagine you want to present a list of all reviews for a product. When a user chooses a review from the list, you’ll show them a view that includes the review’s title, body, and rating; the product it describes; and who wrote the review. That way, your user will be able to click through to more information about the product or reviewing user.
+
+In a relational database, you’d likely have separate tables for the review-specific information and a rating; for the product; and for the user. Your reviews table would include secondary keys with which to join reviews to the users and products tables. Maybe something like this:
+
+.. image:: reviews.png
+
+To get the data you need, your query might look like the SQL query below. By getting UUIDs for the user and product into your client code, you’re able to give the user a way to get user and product information from the review.
+
+ SELECT review.title, review.body, review.rating, review.uuid,
+ user.name, user.uuid, product.name, product.uuid
+ FROM reviews
+ INNER JOIN users
+ ON users.uuid = reviews.authorId
+ INNER JOIN products
+ ON products.uuid = reviews.productId
+ WHERE reviews.uuid = <uuid_for_selected_review>
+
+But due to Cassandra’s distributed, high-scale design, a join such as this wouldn’t work. So in the Usergrid, you’d get the data by first storing it all in one place.
+
+### Using a denormalized model to store (then retrieve) data
+In the Usergrid, a more efficient way to get the same result would start by including related user and product data with the review data. This would give you a single place to get all the data you'll show.
+
+The following shows how that model might look as entities in the Usergrid. (The users and products entities are included here to remind you that they exist, but they aren’t actually used in this denormalization example.)
+
+.. image:: reviews2.png
+
+This use case assumes that your user and product data are already in the data store. In the following API request code, you’re just adding a new review written by a user about a particular product. The JSON body is your new review entity (the JSON here is non-entitized to make it readable).
+
+ POST https://api.usergrid.com/my_org/my_app/reviews -d {
+ "title" : "Tempted to climb in myself.",
+ "body" : "I mean, who doesn't love a bouncy castle? The kids love it!",
+ "rating" : 3,
+ "authorName" : "Jennie",
+ "authorUUID" : <author_uuid>,
+ "authorImage" : "http://<path_to_image>.png",
+ "productUUID" : <product_uuid>,
+ "productImage" : "http://<path_to_image>.jpg",
+ "productName" : "Magic Castle Bounce House Inflatable Bouncer"
+ }
+
+Notice that you’re adding user and product data (which your client code would have at hand when the user posts the review) when you’re adding the review-specific data.
+
+Retrieving all the data from one place
+You’d get the review, including the subset of product and user data you need right away, by making one API call such as the following (note there’s no SQL-like query string needed):
+
+ GET http://api.usergrid.com/my_org/my_app/reviews/<review_uuid>
+
+Your result might look like this. The highlighted lines show data you'd present to the user.
+
+ {
+ "action" : "get",
+ "application" : "<app_uuid>",
+ "params" : { },
+ "path" : "/reviews",
+ "uri" : "https://api.usergrid.com/my_org/my_app/reviews",
+ "entities" : [ {
+ "uuid" : "<review_uuid>",
+ "type" : "review",
+ "created" : 1395410364673,
+ "modified" : 1395410364673,
+ "authorName" : "Jennie",
+ "authorImage" : "<path_to_image>.png",
+ "authorUUID" : "<author_uuid>",
+ "body" : "I mean, who doesn't love a bouncy castle? The kids love it!",
+ "metadata" : {
+ "path" : "/reviews/<review_uuid>"
+ },
+ "productImage" : "http://<path_to_image>.jpg",
+ "productName" : "Magic Castle Bounce House Inflatable Bouncer",
+ "productUUID" : "<product_uuid>",
+ "rating" : 3,
+ "title" : "Tempted to climb in myself."
+ } ],
+ "timestamp" : 1395764951934,
+ "duration" : 16,
+ "organization" : "my_org",
+ "applicationName" : "my_app"
+ }
+
+This gives you, in one request, all the review information you’d planned on presenting to your app’s users for a single view. Your client code could retrieve the review entity in the result, along with the product and user data, then present it all as a review.
+
+Best practice: Connect entities to simplify scoped requests
+Another way to streamline your requests is to connect entities by using the built-in connections feature. In a sense, a connection can replace the WHERE clause of a query you might have written.
+
+Getting back to the review example, imagine you want to retrieve all of the reviews written by a particular user. In the relational example, you might have an SQL query such as this:
+
+ SELECT * FROM reviews WHERE authorId = <user_uuid>;
+
+Even in the Usergrid, you could use a similar syntax in a query string appended to an API path. Working from the review entity model in the preceding example, that might look like this (though yours would likely entitize the spaces):
+
+ GET http://api.usergrid.com/my_org/my_app/reviews?ql=select * where
+ authorUUID=<user_uuid>
+
+But if this is an API call you’re going to be making often, there’s a better way. Instead, create a connection between the review and the user when your code creates the review. You can connect entities with a verb that describes their relationship to one another.
+
+The following creates Jennie’s review and at the same time connects her as the person who “wrote” it. (For easier reading, this example contains spaces you wouldn’t be able to include.)
+
+ POST http://api.usergrid.com/my_org/my_app/users/jennie/wrote/reviews {
+ "title" : "Tempted to climb in myself.",
+ "body" : "I mean, who doesn't love a bouncy castle? The kids love it!",
+ "rating" : 3,
+ "authorName" : "Jennie",
+ "authorImage" : "http://<path_to_image>.png",
+ "productName" : "Magic Castle Bounce House Inflatable Bouncer",
+ "productImage" : "http://<path_to_image>.jpg"
+ }
+
+When reading the data, you’d retrieve all of the reviews Jennie has written with a URL that’s nearly identical, minus the JSON:
+
+ GET http://api.usergrid.com/my_org/my_app/users/jennie/wrote/reviews
+
+Your request result would look something like the following. Here, the entities array returned contains the reviews you connected with Jennie (though there’s only one in this example). The connection-specific metadata is highlighted.
+
+ {
+ "action" : "get",
+ "application" : "<app_uuid>",
+ "params" : { },
+ "path" : "/users/<user_uuid>/wrote",
+ "uri" : "https://api.usergrid.com/my_org/my_app/users/<user_uuid>/wrote",
+ "entities" : [ {
+ "uuid" : "<review_uuid>",
+ "type" : "review",
+ "created" : 1395410364673,
+ "modified" : 1395410364673,
+ "authorName" : "Jennie",
+ "authorImage" : "http://<path_to_image>.png",
+ "authorUUID" : "<user_uuid>",
+ "body" : "I mean, who doesn't love a bouncy castle? Kids love it!",
+ "metadata" : {
+ "connecting" : {
+ "wrote" : "/users/<user_uuid>/wrote/<review_uuid>/connecting/wrote"
+ },
+ "path" : "/users/<user_uuid>/wrote/<review_uuid>",
+ },
+ "productImage" : "http://<path_to_image>.jpg",
+ "productName" : "Magic Castle Bounce House Inflatable Bouncer",
+ "productUUID" : "<product_uuid>",
+ "rating" : 3,
+ "title" : "Tempted to climb in myself."
+ } ],
+ "timestamp" : 1395777037697,
+ "duration" : 19,
+ "organization" : "my_org",
+ "applicationName" : "my_app"
+ }
+
+To retrieve a particular review written by Jennie, you could use something like the following:
+
+ GET http://api.usergrid.com/my_org/my_app/users/jennie/wrote/reviews/<review_uuid>
+
+You can create connections to set up relationships you can use to later retrieve data quickly and with a simple syntax.
+
+For example, when creating a connected entity (such as the review entity here), you can at the same time create other connections to connect the product to the new review, then connect the product to its reviewer (paths are abbreviated in these examples):
+
+ POST /users/jennie/wrote/reviews {<review_entity_json>}
+ POST /products/<reviewed_product_uuid>/reviewedIn/reviews/<new_review_uuid>
+ POST /products/<reviewed_product_uuid>/reviewedBy/users/jennie
+
+Having created these connections for each review you post, in addition to getting the review the user wrote, you could later also:
+
+Get the reviews for a product:
+
+ GET /products/<reviewed_product_uuid>/reviewedIn/reviews
+ Get the users who reviewed the product:
+ GET /products/<reviewed_product_uuid>/reviewedBy/users
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/2a55601f/content/docs/_sources/entity-connections/connecting-entities.txt
----------------------------------------------------------------------
diff --git a/content/docs/_sources/entity-connections/connecting-entities.txt b/content/docs/_sources/entity-connections/connecting-entities.txt
new file mode 100644
index 0000000..1c6219e
--- /dev/null
+++ b/content/docs/_sources/entity-connections/connecting-entities.txt
@@ -0,0 +1,60 @@
+# Connecting entities
+
+When creating a connection, if you specify the collection of the entity being connected to, you can create the connection using the value of its 'name' property or its UUID.
+
+## Request syntax
+
+To create a connection, the entity being connected to can either be specified by just its UUID, or both its collection and the value of its 'name' property.
+
+Connect by UUID
+
+ curl -X POST https://api.usergrid.com/<org>/<app>/<connecting_collection>/<connecting_entity>/<relationship>/<connected_entity>
+
+Connect by 'name' property
+
+ curl -X POST https://api.usergrid.com/<org>/<app>/<connecting_collection>/<connecting_entity>/<relationship>/<connected_collection>/<connected_entity>
+
+Parameters
+
+Parameter Description
+--------- -----------
+org Organization UUID or organization name
+app Application UUID or application name
+connecting_collection Name or UUID of the collection of the connecting entity.
+connecting_entity Name or UUID of the connecting entity.
+relationship Type of connection being created (e.g., likes)
+connected_collection Name or UUID of the collection of the entity being connected to.
+connected_entity Name or UUID of the entity being connected to.
+
+If the connecting entity is a 'user' entity, the 'username' should be used rather than the 'name'.
+
+'connected_collection' is not required if the entity being connected to is specified by its UUID.
+
+Example request
+
+ curl -X POST http://api.usergrid.com/your-org/your-app/users/Arthur/likes/6c56ffda-9e75-11e3-99fd-8dd1801e534c
+
+Example Response
+
+ {
+ "action" : "post",
+ "application" : "db1e60a0-417f-11e3-9586-0f1ff3650d20",
+ "params" : { },
+ "path" : "/users/174785aa-8ea8-11e3-ae1f-eb20e5bce407/likes",
+ "uri" : "https://api.usergrid.com/my-org/my-app/users/174785aa-8ea8-11e3-ae1f-eb20e5bce407/likes",
+ "entities" : [ {
+ "uuid" : "6c56ffda-9e75-11e3-99fd-8dd1801e534c",
+ "type" : "user",
+ "name" : "Arthur",
+ "created" : 1393371291725,
+ "modified" : 1393371291725,
+ "metadata" : {
+ "path" : "/users/174785aa-8ea8-11e3-ae1f-eb20e5bce407/likes/6c56ffda-9e75-11e3-99fd-8dd1801e534c"
+ }
+ } ],
+ "timestamp" : 1393371455487,
+ "duration" : 77,
+ "organization" : "your-org",
+ "applicationName" : "your-app"
+ }
+
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/2a55601f/content/docs/_sources/entity-connections/disconnecting-entities.txt
----------------------------------------------------------------------
diff --git a/content/docs/_sources/entity-connections/disconnecting-entities.txt b/content/docs/_sources/entity-connections/disconnecting-entities.txt
new file mode 100644
index 0000000..b52d62d
--- /dev/null
+++ b/content/docs/_sources/entity-connections/disconnecting-entities.txt
@@ -0,0 +1,79 @@
+# Disconnecting entities
+
+To disconnect a user from other data, perform a DELETE operation against the same endpoint at which you posted to create the connection.
+
+## Request syntax
+
+Disconnect by UUID
+
+ curl -X DELETE https://api.usergrid.com/<org>/<app>/<connecting_collection>/<connecting_entity>/<relationship>/<connected_entity>
+
+Disconnect by 'name' property
+
+ curl -X DELETE https://api.usergrid.com/<org>/<app>/<connecting_collection>/<connecting_entity>/<relationship>/<connected_collection>/<connected_entity>
+
+Parameters
+
+Parameter Description
+--------- -----------
+org Organization UUID or organization name
+app Application UUID or application name
+connecting_collection Name or UUID of the collection of the connecting entity.
+connecting_entity Name or UUID of the connecting entity.
+relationship Type of connection being created (e.g., likes)
+connected_collection Name or UUID of the collection of the entity being connected to.
+connected_entity Name or UUID of the entity being connected to.
+
+If the connecting entity is a 'user' entity, the 'username' should be used rather than the 'name'.
+
+'connected_collection' is not required if the entity being connected to is specified by its UUID.Parameter
+
+Example request
+
+ curl -X DELETE https://api.usergrid.com/your-org/your-app/users/Arthur/likes/users/Ford
+
+Example response
+
+ {
+ "action" : "delete",
+ "application" : "k88dh4f-a166-11e2-a7f7-02e81adcf3d0",
+ "params" : { },
+ "path" : "/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes",
+ "uri" : "https://api.usergrid.com/your-org/your-app/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes",
+ "entities" : [ {
+ "uuid" : "5bcc47ca-cfed-11e3-8bde-a7e008061e10",
+ "type" : "user",
+ "created" : 1398810410556,
+ "modified" : 1398810410556,
+ "username" : "Ford",
+ "activated" : true,
+ "metadata" : {
+ "connecting" : {
+ "likes" : "/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10/connecting/likes"
+ },
+ "path" : "/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10",
+ "sets" : {
+ "rolenames" : "/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10/roles",
+ "permissions" : "/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10/permissions"
+ },
+ "connections" : {
+ "friends" : "/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10/friends",
+ "likes" : "/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10/likes"
+ },
+ "collections" : {
+ "activities" : "/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10/activities",
+ "devices" : "/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10/devices",
+ "feed" : "/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10/feed",
+ "groups" : "/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10/groups",
+ "roles" : "/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10/roles",
+ "following" : "/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10/following",
+ "followers" : "/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10/followers"
+ }
+ }
+ } ],
+ "timestamp" : 1398962837195,
+ "duration" : 85,
+ "organization" : "your-org",
+ "applicationName" : "your-app"
+ }
+
\ No newline at end of file