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/07/29 18:06:35 UTC
[4/9] incubator-usergrid git commit: Continuing the conversion of
Usegrid documentation to Markdown.
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/07d14c88/docs/concepts/query-language.md
----------------------------------------------------------------------
diff --git a/docs/concepts/query-language.md b/docs/concepts/query-language.md
deleted file mode 100644
index bd337ac..0000000
--- a/docs/concepts/query-language.md
+++ /dev/null
@@ -1,427 +0,0 @@
-# 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 Apigee 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.
-
-App services 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/07d14c88/docs/concepts/relationships.md
----------------------------------------------------------------------
diff --git a/docs/concepts/relationships.md b/docs/concepts/relationships.md
deleted file mode 100644
index e039e09..0000000
--- a/docs/concepts/relationships.md
+++ /dev/null
@@ -1,100 +0,0 @@
-# Relationships
-
-Creating connections between entities
--------------------------------------
-
-One of the most useful features of App services is the ability to create
-connections between entities. A simple example of this is the
-Twitter-like use of *following*, where one user forms a connection with
-another by subscribing to any tweets they post. [Messagee
-Example](/messagee-example) walks you through an example of following
-other users in our sample app, *Messagee*. Here is the basic format:
-
- POST https://api.usergrid.com/my-org/my-app/users/fred/following/users/barney
-
-This API call results in two users, Fred and Barney, linked with a
-connection where Fred is following Barney.
-
-If you create a *following* connection between two users, Apache Usergrid
-automatically creates a virtual connection called *followers* that
-mirrors the *following* connection. In other words, if you create a
-connection where Fred is following Barney, Apache Usergrid automatically
-creates a virtual connection where Fred is a follower of Barney.
-
-Note that there is no mirror connection established. Apache Usergrid only
-creates a mirror connection when you create a *following* connection. It
-does not create a mirror connection for other verbs such as likes.
-
-You can see all the users that Fred is following, in this case only
-Barney, by making the following API call:
-
- GET https://api.usergrid.com/my-org/my-app/users/fred/following
-
-You can see all of barney’s followers, in this case only Fred, by making
-the following API call:
-
- GET https://api.usergrid.com/my-org/my-app/users/barney/followers
-
-The *followers* connection is a virtual connection because you can’t use
-it to link two entities. In other words, you can’t make fred a follower
-of barney by using a *followers* connection. **This is wrong:**
-
- POST https://api.usergrid.com/my-org/my-app/users/barney/followers/users/fred
-
-To create a *following* connection with the users switched, so that
-Barney is following Fred, do this:
-
- POST https://api.usergrid.com/my-org/my-app/users/barney/following/users/fred
-
-You can now see Fred’s followers (only Barney) by making the following
-call:
-
- GET https://api.usergrid.com/my-org/my-app/users/fred/followers
-
-Creating other connections
---------------------------
-
-You can extend this connection structure to create connections using any
-"verb" that can link two entities. For example, you could use likes to
-denote a connection between a user and his dog. First, create a dogs
-collection:
-
- POST https://api.usergrid.com/my-org/my-app/dogs
-
-Then populate this collection with a new dog named Dino:
-
- POST https://api.usergrid.com/my-org/my-app/dogs {"name" : "dino"}
-
-Then create a likes connection between Fred and his dog Dino:
-
- POST https://api.usergrid.com/my-org/my-app/users/fred/likes/dogs/dino
-
-Getting connections
--------------------
-
-### Get all connections for an entity
-
-To get a list that only contains the connections, do a GET on the
-connections sub-property of the entity:
-
- GET https://api.usergrid.com/my-org/my-app/users/fred/connections
-
-### Get information on a specific connection type
-
-To get a list of users who like Fred:
-
- GET https://api.usergrid.com/my-org/my-app/users/fred/connecting/likes
-
-To get a list of all dogs that Fred likes:
-
- GET https://api.usergrid.com/my-org/my-app/users/fred/likes/dog
-
-Deleting a connection
----------------------
-
-You can delete a connection in a way similar to creating one. Just
-replace the POST method with the DELETE method. For example, you can
-delete the connection between fred and barney with the following API
-call:
-
- DELETE https://api.usergrid.com/my-org/my-app/users/fred/following/barney
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/07d14c88/docs/concepts/roles-and-permissions.md
----------------------------------------------------------------------
diff --git a/docs/concepts/roles-and-permissions.md b/docs/concepts/roles-and-permissions.md
deleted file mode 100644
index d237c13..0000000
--- a/docs/concepts/roles-and-permissions.md
+++ /dev/null
@@ -1,18 +0,0 @@
-# Roles & Permissions
-
-## Roles
-
-A role represents a set of permissions that enable certain operations to
-be performed on a specific endpoint. You can assign a user to a role,
-and in this way give the user the permissions associated with that role.
-
-**Note:** The /rolenames endpoint is no longer valid. If your code currently
-makes calls to /rolenames, you need to change the calls to use /roles.
-
-## Permissions
-
-Each role contains multiple permissions. Permissions work by whitelisting by default, meaning any permission that is not explicitely granted is denied by default. Permission is an HTTP verb (GET to allow reads, POST to allow creation, PUT to allow edits and DELETE to allow deletes) combined with a path, with optional wildcards. For example the permission put:/users/* allows editing any user.
-
-Permissions can be added to roles, groups or to users directly, and a user’s permission is the combination of its personal permissions and the permissions of any role he’s been assigned, and the permissions of any group he’s a member of.
-
-Permissions are only valid within the scope of a single application, so the permission paths do not need to be prefixed with /org\_name\_or\_uuid/app\_name\_or\_uuid.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/07d14c88/docs/concepts/users-devices.md
----------------------------------------------------------------------
diff --git a/docs/concepts/users-devices.md b/docs/concepts/users-devices.md
deleted file mode 100644
index 4da5699..0000000
--- a/docs/concepts/users-devices.md
+++ /dev/null
@@ -1,108 +0,0 @@
-# Users & Devices
-
-Users and Devices are the primary ways to identify access to the system. Devices are great to track anonymous access, while Users allow you to model signing up, signing in, etc.
-
-Users
------
-
-### Properties
-
-Property Type Description
------------- --------- ---------------------------------------------------------------------------------
- uuid UUID User’s unique entity ID
- type string Type of entity, in this case “user”
- created long [UNIX timestamp](http://en.wikipedia.org/wiki/Unix_time) of entity creation
- modified long [UNIX timestamp](http://en.wikipedia.org/wiki/Unix_time) of entity modification
- username string Valid and unique string username (mandatory)
- password string User password
- email string Valid and unique email address
- name string User display name
- activated boolean Whether the user account is activated
- disabled boolean Whether the user account is administratively disabled
- firstname string User first name
- middlename string User middle name
- lastname string User last name
- picture string User picture
-
-
-### Sets
-
- Set Type Description
- ------------- -------- ---------------------------------------
- connections string Set of connection types (e.g., likes)
- rolenames string Set of roles assigned to a user
- permissions string Set of user permissions
- credentials string Set of user credentials
-
-### Relationshops
-
- Collection Type Description
- ------------ ---------- -----------------------------------------------------
- groups group Collection of groups to which a user belongs
- devices device Collection of devices in the service
- activities activity Collection of activities a user has performed
- feed activity Inbox of activity notifications a user has received
- roles role Set of roles assigned to a user
-
-### Facebook Sign-in
-
-You can authenticate your Apache Usergrid requests by logging into
-Facebook. To access Apache Usergrid resources, you need to provide an
-access token with each request (unless you use the sandbox app). You can
-get an access token by connecting to an appropriate web service endpoint
-and providing the correct client credentials — this is further described
-in [Authenticating users and application
-clients](/authenticating-users-and-application-clients). However, you
-can also obtain an access token by logging into Facebook.
-
-To enable authentication to Apache Usergrid through Facebook, do the
-following in your app:
-
-1. Make a login call to the Facebook API (do this using the [Facebook
- SDK](https://developers.facebook.com/docs/sdks/) or
- [API](https://developers.facebook.com/docs/facebook-login/)). If the
- login succeeds, a Facebook access token is returned.
-2. Send the Facebook access token to Apache Usergrid. If the Facebook
- access token is valid and the user does not already exist in App
- Services, Apache Usergrid provisions a new Apache Usergrid user. It also
- returns an Apache Usergrid access token, which you can use for
- subsequent Apache Usergrid API calls. Behind the scenes, Apache Usergrid
- uses the Facebook access token to retrieve the user's profile
- information from Facebook.
-
- If the Facebook access token is invalid, Facebook returns an OAuth
- authentication error, and the login does not succeed.
-
-The request to authenticate to Apache Usergrid using a Facebook access
-token is:
-
- GET https://api.usergrid.com/{my_org}/{my_app}/auth/facebook?fb_access_token={fb_access_token}
-
-where:
-
-* {my\_org} is the organization UUID or organization name.\
-* {my\_app} is the application UUID or application name.\
-* {fb\_access\_token} is the Facebook access token.
-
-
-Devices
--------
-
-### Properties
-
-Property Type Description
----------- -------- ---------------------------------------------------------------------------------
- uuid UUID Entity unique ID
- type string Entity type (e.g., device)
- created long [UNIX timestamp](http://en.wikipedia.org/wiki/Unix_time) of entity creation
- modified long [UNIX timestamp](http://en.wikipedia.org/wiki/Unix_time) of entity modification
- name string Device name (mandatory)
-
-
-### Relationships
-
-Devices have the following associated collection.
-
- Collection Type Description
- ------------ ------ -----------------------------------------------
- users user Collection of users to which a device belongs
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/07d14c88/docs/conf.py
----------------------------------------------------------------------
diff --git a/docs/conf.py b/docs/conf.py
index 0ae99ab..1a385fb 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -58,7 +58,7 @@ master_doc = 'index'
# General information about the project.
project = u'Apache Usergrid'
-copyright = u'2013-2014, Apache Usergrid'
+copyright = u'2013-2015, Apache Usergrid'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
@@ -269,5 +269,5 @@ sys.path.insert(0, os.path.abspath('.'))
sys.path.insert(0, os.path.abspath('./lib'))
extensions += ["sphinxcontrib_markdown"]
-markdown_title = 'Apache Usergrid Documents'
+markdown_title = 'Apache Usergrid Documentation'
source_suffix = '.md'
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/07d14c88/docs/counters-and-events/events-and-counters.md
----------------------------------------------------------------------
diff --git a/docs/counters-and-events/events-and-counters.md b/docs/counters-and-events/events-and-counters.md
new file mode 100644
index 0000000..1d6cdcd
--- /dev/null
+++ b/docs/counters-and-events/events-and-counters.md
@@ -0,0 +1,268 @@
+# Events and counters
+
+Events are typically used for application logging. For example, they
+could be used to log error messages that a system administrator might
+review at a later time. The event mechanism is optimized to handle large
+numbers of events, so it is an ideal mechanism for logging in your
+application.
+
+You can link events to specific users, groups, or custom-defined
+categories. When created with these links, events offer a powerful tool
+for running highly targeted, custom reports.
+
+Events are also the primary way to store custom counter data for
+analytics. See Counters (below) for further details.
+
+
+Event properties
+----------------
+
+You can pass various system-defined properties for an event. For
+example, you can specify a user property, with a uuid as its value. This
+will link the event to the user and can be used to query against the
+events queue (see Categorization below). The same is true for the group
+property. Pass it with a uuid as the value and the event will be linked
+to the group. To include a uuid of a user or group, add the uuid to the
+request body, for example:
+
+ POST https://api.usergrid.com/my-org/my-app/events {"timestamp":0, "category" : "advertising", "counters" : {"ad_clicks" : 5},"user" : "1234891-477d-11e1-b2bd-22005a1c4e22", "group" : "75577d891-347d-2231-b5bd-23400a1c4e22"}
+
+The response body would look something like this:
+
+ {
+ "action": "post",
+ "application": "7fb8d891-477d-11e1-b2bd-22000a1c4e22",
+ "params": {},
+ "path": "/events",
+ "uri": "https://api.usergrid.com/22000a1c4e22-7fb8d891-477d-11e1-b2bd/7fb8d891-477d-11e1-b2bd-22000a1c4e22/events",
+ "entities": [
+ {
+ "uuid": "ce07ea3c-68b5-11e1-a586-9227e40e3559",
+ "user": "1234891-477d-11e1-b2bd-22005a1c4e22",
+ "group": "75577d891-347d-2231-b5bd-23400a1c4e22",
+ "type": "event",
+ "created": 1331166585282,
+ "modified": 1331166585282,
+ "counters": {
+ "ad_clicks": 5
+ },
+ "metadata": {
+ "path": "/events/ce07ea3c-68b5-11e1-a586-9227e40e3559"
+ },
+ "timestamp": 1331166585282
+ }
+ ],
+ "timestamp": 1331166585018,
+ "duration": 919,
+ "organization": "my-org",
+ "applicationName": "my-app"
+ }
+
+You can also create application-specific event properties in addition to
+these predefined properties. The system-defined properties are reserved.
+You cannot use these names to create other properties for an event
+entity. In addition the events name is reserved for the events
+collection — you can't use it to name another collection.
+
+The System-defined properties are as follows:
+
+ Property Type Description
+ ----------- -------- -------------------------------------------------------------------------------------------
+ uuid UUID Event’s unique entity ID
+ type String "event"
+ created long [UNIX timestamp](http://en.wikipedia.org/wiki/Unix_time) of entity creation
+ modified long [UNIX timestamp](http://en.wikipedia.org/wiki/Unix_time) of entity modification
+ timestamp long [UNIX timestamp](http://en.wikipedia.org/wiki/Unix_time) of application event (mandatory)
+ user UUID UUID of application user that posted the event
+ group UUID UUID of application group that posted the event
+ category string Category used for organizing similar events
+ counters map Counter used for tracking number of similar events
+ message string Message describing event
+
+### Categorizing events
+
+As mentioned previously, you can link an event to a user or a group using a standard [Relationship](/docs/relationships).
+This enables you to categorize and qualify event data for use in
+tracking and analysis. For example, linking events to users and groups,
+enables you to track how often people use a feature. Not only can you
+determine the total number of users that used the feature, but also
+which groups contain users that made the most use of the feature. Or,
+you could provide a location with the event, so you could see how often
+a feature was used by people in San Francisco versus Los Angeles.
+
+Counters
+--------
+
+User-defined counters are used in conjunction with events to keep
+statistics on many aspects of an application. User-defined counters are
+JSON objects that are added to events when they are posted. The act of
+posting an event increments the counter. Once created, user-defined
+counters can be used to get reports.
+
+**Note:** It may take up to 30 seconds for a counter to be updated.
+
+### User-Defined Counters
+
+With Apache Usergrid, you can define your own counters. Some of the things
+that you might track with a user-defined counter are:
+
+- How many times people click on the help button in your application.
+- How many times your game is played each day.
+- How many times your banner ads are clicked each day.
+
+You can choose any name for a user-defined counter. For example, the
+counter for the help button might be named “help\_button” or
+“help\_button\_clicks”.
+
+To create a user-defined counter, you post to the events collection and
+specify the name and increment value of the counter in the request body.
+The increment value is the value that the counter is incremented by for
+each tracked event. An increment value of 1, means that the counter is
+increment by 1 for each tracked event. You could also specify a higher
+increment value, such as 15, which would increment the value by that
+number, or a negative number, which would decrement the value. You can
+also reset the value of the counter, by specifying an increment value of
+0.
+
+When a counter is incremented by an event, there will be a 20-30 second
+delay between when the event is posted and when the counter is
+incremented.
+
+As an example, here's how to create a user-defined counter named
+“button\_clicks” with an increment value of 1:
+
+ POST https://api.usergrid.com/my-org/my-app/events {"counters" : {"button_clicks" : 1},"timestamp" : "0"}
+
+The response body would look something like this:
+
+ {
+ "action": "post",
+ "path": "/events",
+ "uri": "http://api.usergrid.com/438a1ca1-cf9b-11e0-bcc1-12313f0204bb/events",
+ "entities": [
+ {
+ "uuid": "39d41c46-d8e4-11e0-bcc1-12313f0204bb",
+ "type": "event",
+ "timestamp": 1315353555546016,
+ "category":"advertising",
+ "counters": {
+ "button_clicks": 1
+ },
+ "created": 1315353555546016,
+ "modified": 1315353555546016,
+ "metadata": {
+ "path": "/events/39d41c46-d8e4-11e0-bcc1-12313f0204bb"
+ }
+ }
+ ],
+ "timestamp": 1315353555537,
+ "duration": 110,
+ "organization": "my-org",
+ "applicationName": "my-app"
+ }
+
+### Counter hierarchy
+
+Counters are hierarchical in their structure and in the way they are
+incremented. Each level of the hierarchy is separated by the dot “.”
+operator. The hierarchical structure can be useful if you want to store
+or view statistics in a hierarchical way. For example, suppose you want
+to log errors that your app generates. One way to do this, is to fire an
+event every time an error occurs, by creating a counter called “errors”.
+However, you can get more detail by adding additional parameters to the
+counter. Imagine that you want to track errors in a specific module and
+function within that module, say module\_1, function\_1, you could use a
+counter like this:
+
+ errors.module_1.function_1
+
+And then for a different function in the same module:
+
+ errors.module_1.function_2
+
+And then for a different function in a different module:
+
+ errors.module_2.function_3
+
+If each of the preceding examples were called once, the resulting values
+would be:
+
+ errors = 3
+ errors.module_1 = 2
+ errors.module_1.function_1 = 1
+ errors.module_1.function_2 = 1
+ errors.module_2 = 1
+ errors.module_2.function_3 = 1
+
+This tells you that there were 3 errors in the application, with 2 of
+those errors in module\_1. You can then drill down further to see errors
+in specific functions.
+
+### Using counters in time series queries
+
+Knowing the value of a counter is useful. However, you often need to
+know how the value varies over time. Fortunately, the API provides a
+method for you to view this data over any time interval or level of
+granularity.
+
+For example, let’s say you’re incrementing a counter every time someone
+launches your application. You might be interested in which days of the
+week the application sees the most usage. Using the API, you can examine
+the counter over a set of weeks, with the data split into daily
+intervals. Using this information, you can see which are your peak days
+of usage. You can also view usage across a single day, so you can see if
+your application is used more in the mornings or the evenings. For
+business reporting, you may be more interested in monthly reporting.
+
+Note that the system is able to provide you with the report data as you
+need it. The data is maintained in real-time so it can be viewed
+instantly.
+
+### Retrieving counter data
+
+To retrieve counter data, you issue a GET request to the /counters
+endpoint. This is a special, built-in collection that gives you access
+to all the counters currently in the system. The API also provides a
+number of parameters that you can use to search for counter data, as
+follows:
+
+ Parameter Type Description
+ ------------- ------------------------------------------------------------------------------------ ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+ start\_time An [Epoch(Unix)](http://en.wikipedia.org/wiki/Unix_time) timestamp in milliseconds The beginning of the time period to search
+ end\_time An [Epoch(Unix)](http://en.wikipedia.org/wiki/Unix_time) timestamp in milliseconds The end of the time period to search
+ counter string The name of a specific counter to search. You can specify more than one counter in a query (for example, counter=counter1&counter=counter2...)
+ resolution string The interval at which counters are displayed. For example, if the interval is day, and the start time and end time values span 4 days, you will get aggregate counts for each of the 4 days. Possible values are all, minute, five\_minutes, half\_hour, hour, six\_day, day, week, and month.
+
+For example, to retrieve a time range of values, with a granularity of
+"day", for a counter called "button\_clicks", the GET request would look
+like this:
+
+ GET /my-org/my-app/counters?start_time=1315119600000&end_time=1315724400000&resolution=day&counter=button_clicks
+
+The response body would look something like this:
+
+ {
+ action: "get",
+ uri: "http://api.usergrid.com/438a1ca1-cf9b-11e0-bcc1-12313f0204bb/counters",
+ timestamp: 1315354369272,
+ duration: 28,
+ counters: [
+ {
+ name: "button_clicks",
+ values: [
+ {
+ value: 2
+ timestamp: 1315180800000
+ },
+ {
+ value: 1
+ timestamp: 1315267200000
+ },
+ {
+ value: 1
+ timestamp: 1315353600000
+ }
+ ]
+ }
+ ]
+ }
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/07d14c88/docs/data-queries/advanced-query-usage.md
----------------------------------------------------------------------
diff --git a/docs/data-queries/advanced-query-usage.md b/docs/data-queries/advanced-query-usage.md
new file mode 100644
index 0000000..4e6e7ba
--- /dev/null
+++ b/docs/data-queries/advanced-query-usage.md
@@ -0,0 +1,17 @@
+# Advanced query usage
+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.
+Attaching a query to all API calls
+
+## JavaScript SDK only
+The following feature is currently only supported by the Apigee JavaScript SDK
+In some cases, it may be convenient to attach a query or other URI parameter to every call you make to API BaaS, such as a custom identifier or token. To do this with the Apigee JavaScript SDK, add a qs property to your Apigee.Client object when you initialize the SDK. For more on initializing the SDK, see our install guide.
+
+For example, the following would append ?custom_id=1234 to every call sent from the Apigee JavaScript SDK to API BaaS:
+
+ var options = {
+ orgName:'yourOrg',
+ appName:'yourApp',
+ qs:'custom_id=1234'
+ }
+ var dataClient = new Apigee.Client(options);
+
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/07d14c88/docs/data-queries/operators-and-types.md
----------------------------------------------------------------------
diff --git a/docs/data-queries/operators-and-types.md b/docs/data-queries/operators-and-types.md
new file mode 100644
index 0000000..c779809a
--- /dev/null
+++ b/docs/data-queries/operators-and-types.md
@@ -0,0 +1,122 @@
+# Supported query operators & data types
+
+The following operators and data types are supported by the SQL-like query language in API BaaS.
+
+## Operators
+
+.. raw:: html
+ <table class="usergrid-table">
+ <tr>
+ <td>Operator</td>
+ <td>Purpose</td>
+ <td>Example</td>
+ </tr>
+ <tr>
+ <td>'<' or 'lt'</td>
+ <td>Less than</td>
+ <td>select * where quantity > '1000'</td>
+ </tr>
+ <tr>
+ <td>'<=' or 'lte'</td>
+ <td>Less than or equal to</td>
+ <td>Example</td>
+ </tr>
+ <tr>
+ <td>'=' or 'eq'</td>
+ <td>Equals</td>
+ <td>select * where price = '20.00'</td>
+ </tr>
+ <tr>
+ <td>'>=' or 'gte'</td>
+ <td>Greater than or equal to </td>
+ <td>select * where quantity >= '1000'</td>
+ </tr>
+ <tr>
+ <td>'>' or 'gt'</td>
+ <td>Greater than</td>
+ <td>select * where quantity > '1000'</td>
+ </tr>
+ <tr>
+ <td>not <some_expression></td>
+ <td>Subtraction of results</td>
+ <td>select * where quantity < '4000' and not quantity = '2000'</td>
+ </tr>
+ <tr>
+ <td>and</td>
+ <td>Union of results</td>
+ <td>select * where quantity > '1000' and quantity < '4000'</td>
+ </tr>
+ <tr>
+ <td>or</td>
+ <td>Intersection of results</td>
+ <td>select * where quantity = '1000' or quantity = '4000'</td>
+ </tr>
+ <tr>
+ <td>contains</td>
+ <td>Narrow by contained text</td>
+ <td>select * where title contains 'tale'</td>
+ </tr>
+ </table>
+
+
+## Data types
+
+As you develop queries, remember that entity properties each conform to a particular data type. 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 to ensure that query results are as you expect them to be.
+
+For example, if you create an entity with a price property with a value of 100.00, querying for 100 will return no results, since the API expected a decimal-delimited float value in your query.
+
+For a list of property data types for each default entities, see Default Data Entity Types.
+
+.. raw:: html
+ <table class="usergrid-table">
+ <tr>
+ <td>string</td>
+ <td><pre>'value', unicode '\uFFFF', octal '\0707'</pre></td>
+ </tr>
+ <tr>
+ <td>long</td>
+ <td><pre>1357412326021</pre> <br> Timestamps are typically stored as long values.</td>
+ </tr>
+ <tr>
+ <td>float</td>
+ <td><pre>10.1, -10.1, 10e10, 10e-10, 10E10, 10E-10</pre> <br>
+ Your query must be specific about the value you're looking for, down to the value
+ (if any) after the decimal point.</td>
+ </tr>
+ <tr>
+ <td>boolean</td>
+ <td><pre>true | false</pre></td>
+ </tr>
+ <tr>
+ <td>UUID</td>
+ <td><pre>ee912c4b-5769-11e2-924d-02e81ac5a17b</pre></td>
+ </tr>
+ <tr>
+ <td>Array</td>
+ <td><pre>["boat", "car", "bike"]</pre></td>
+ </tr>
+ <tr>
+ <td>object</td>
+ <td><p>For a JSON object like this one:</p>
+ <pre>
+ {
+ "items": [
+ {
+ "name": "rocks"
+ },
+ {
+ "name": "boats"
+ }
+ ]
+ }
+ </pre>
+ <p>you can use dot notation to reach property values in the object:</p>
+ <pre>
+ /mycollection/thing?ql="select * where items.name = 'rocks'"
+ </pre>
+ <p>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.</p>
+ <p>Please note that object properties are not indexed. This means queries
+ using dot-notation will be much slower than queries on indexed entity properties.</p></td>
+ </tr>
+ </table>
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/07d14c88/docs/data-queries/query-language.md
----------------------------------------------------------------------
diff --git a/docs/data-queries/query-language.md b/docs/data-queries/query-language.md
new file mode 100644
index 0000000..bd337ac
--- /dev/null
+++ b/docs/data-queries/query-language.md
@@ -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 Apigee 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.
+
+App services 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/07d14c88/docs/data-queries/query-parameters.md
----------------------------------------------------------------------
diff --git a/docs/data-queries/query-parameters.md b/docs/data-queries/query-parameters.md
new file mode 100644
index 0000000..50f1596
--- /dev/null
+++ b/docs/data-queries/query-parameters.md
@@ -0,0 +1,158 @@
+# 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.
+
+## 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.
+
+For more information, see our API BaaS DBMS overview and Data store best practices.
+
+### 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.
+
+.. raw:: html
+ <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.
+
+.. raw:: html
+ <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:
+
+.. raw:: html
+ <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:
+
+.. raw:: html
+ <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
+
+.. raw:: html
+ <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/07d14c88/docs/data-queries/querying-your-data.md
----------------------------------------------------------------------
diff --git a/docs/data-queries/querying-your-data.md b/docs/data-queries/querying-your-data.md
new file mode 100644
index 0000000..9f3abac
--- /dev/null
+++ b/docs/data-queries/querying-your-data.md
@@ -0,0 +1,119 @@
+# 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 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.
+
+## Basic query usage
+
+The following examples show how to query the Apigee API to return the first 5 entities in the users collection that contain the property status:'active'.
+
+### 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.
+
+For more information, see our API BaaS DBMS overview and Data store best practices.
+
+### 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/07d14c88/docs/data-storage/cassandra.png
----------------------------------------------------------------------
diff --git a/docs/data-storage/cassandra.png b/docs/data-storage/cassandra.png
new file mode 100644
index 0000000..ac72781
Binary files /dev/null and b/docs/data-storage/cassandra.png differ