| |
| |
| <!DOCTYPE html> |
| <!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]--> |
| <!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]--> |
| <head> |
| <meta charset="utf-8"> |
| |
| <meta name="viewport" content="width=device-width, initial-scale=1.0"> |
| |
| <title>Query Language — Apache Usergrid 1.0 documentation</title> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <link rel="stylesheet" href="../_static/css/theme.css" type="text/css" /> |
| |
| |
| |
| |
| |
| <link rel="top" title="Apache Usergrid 1.0 documentation" href="../index.html"/> |
| |
| |
| <script src="../_static/js/modernizr.min.js"></script> |
| |
| </head> |
| |
| <body class="wy-body-for-nav" role="document"> |
| |
| <div class="wy-grid-for-nav"> |
| |
| |
| <nav data-toggle="wy-nav-shift" class="wy-nav-side"> |
| <div class="wy-side-nav-search"> |
| |
| |
| |
| <a href="../index.html" class="icon icon-home"> Apache Usergrid |
| |
| |
| |
| </a> |
| |
| |
| |
| |
| <div class="version"> |
| 1.0 |
| </div> |
| |
| |
| |
| |
| <div role="search"> |
| <form id="rtd-search-form" class="wy-form" action="../search.html" method="get"> |
| <input type="text" name="q" placeholder="Search docs" /> |
| <input type="hidden" name="check_keywords" value="yes" /> |
| <input type="hidden" name="area" value="default" /> |
| </form> |
| </div> |
| |
| |
| </div> |
| |
| <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation"> |
| |
| |
| |
| <p class="caption"><span class="caption-text">Introduction</span></p> |
| <ul> |
| <li class="toctree-l1"><a class="reference internal" href="../introduction/usergrid-features.html">Usergrid Features</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../introduction/data-model.html">Usergrid Data model</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../introduction/async-vs-sync.html">Async vs. sync calls</a></li> |
| </ul> |
| <p class="caption"><span class="caption-text">Getting Started</span></p> |
| <ul> |
| <li class="toctree-l1"><a class="reference internal" href="../getting-started/creating-a-new-application.html">Creating a new application</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../getting-started/creating-account.html">Creating an Usergrid Account</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../getting-started/using-a-sandbox-app.html">Using a Sandbox Application</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../getting-started/using-the-api.html">Using the API</a></li> |
| </ul> |
| <p class="caption"><span class="caption-text">Data Storage</span></p> |
| <ul> |
| <li class="toctree-l1"><a class="reference internal" href="../data-storage/data-store-dbms.html">The Usergrid Data Store</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../data-storage/optimizing-access.html">Data Store Best Practices</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../data-storage/collections.html">Collections</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../data-storage/entities.html">Entities</a></li> |
| </ul> |
| <p class="caption"><span class="caption-text">Data Queries</span></p> |
| <ul> |
| <li class="toctree-l1"><a class="reference internal" href="querying-your-data.html">Querying your data</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="query-parameters.html">Query parameters & clauses</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="operators-and-types.html">Query operators & data types</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="advanced-query-usage.html">Advanced query usage</a></li> |
| </ul> |
| <p class="caption"><span class="caption-text">Entity Connections</span></p> |
| <ul> |
| <li class="toctree-l1"><a class="reference internal" href="../entity-connections/connecting-entities.html">Connecting entities</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../entity-connections/retrieving-entities.html">Retrieving connections</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../entity-connections/disconnecting-entities.html">Disconnecting entities</a></li> |
| </ul> |
| <p class="caption"><span class="caption-text">Security & Authentication</span></p> |
| <ul> |
| <li class="toctree-l1"><a class="reference internal" href="../security-and-auth/app-security.html">Security & token authentication</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../security-and-auth/using-permissions.html">Using permissions</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../security-and-auth/authenticating-users-and-application-clients.html">Authenticating users & app clients</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../security-and-auth/user-authentication-types.html">Authentication levels</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../security-and-auth/changing-token-time-live-ttl.html">Changing token expiration (time-to-live)</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../security-and-auth/authenticating-api-requests.html">Authenticating API requests</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../security-and-auth/revoking-tokens-logout.html">Revoking tokens (logout)</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../security-and-auth/facebook-sign.html">Facebook sign in</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../security-and-auth/securing-your-app.html">Security best practices</a></li> |
| </ul> |
| <p class="caption"><span class="caption-text">User Management & Social Graph</span></p> |
| <ul> |
| <li class="toctree-l1"><a class="reference internal" href="../user-management/user-management.html">User management & social graph</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../user-management/working-user-data.html">Working with User Data</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../user-management/group.html">Working with group data</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../user-management/activity.html">Activity</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../user-management/user-connections.html">Social Graph Connections</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../user-management/user-connections.html#creating-other-connections">Creating other connections</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../user-management/messagee-example.html">App Example - Messagee</a></li> |
| </ul> |
| <p class="caption"><span class="caption-text">Geo-location</span></p> |
| <ul> |
| <li class="toctree-l1"><a class="reference internal" href="../geolocation/geolocation.html">Geolocating your Entities</a></li> |
| </ul> |
| <p class="caption"><span class="caption-text">Assets & Files</span></p> |
| <ul> |
| <li class="toctree-l1"><a class="reference internal" href="../asset-and-files/uploading-assets.html">Uploading assets</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../asset-and-files/retrieving-assets.html">Retrieving assets</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../asset-and-files/folders.html">Folders</a></li> |
| </ul> |
| <p class="caption"><span class="caption-text">Counters & Events</span></p> |
| <ul> |
| <li class="toctree-l1"><a class="reference internal" href="../counters-and-events/events-and-counters.html">Counters & events</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../counters-and-events/creating-and-incrementing-counters.html">Creating & incrementing counters</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../counters-and-events/creating-and-incrementing-counters.html#decrementing-resetting-counters">Decrementing/resetting counters</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../counters-and-events/creating-and-incrementing-counters.html#using-counters-hierarchically">Using counters hierarchically</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../counters-and-events/retrieving-counters.html">Retrieving counters</a></li> |
| </ul> |
| <p class="caption"><span class="caption-text">Organizations & Applications</span></p> |
| <ul> |
| <li class="toctree-l1"><a class="reference internal" href="../orgs-and-apps/managing.html">Organization & application management</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../orgs-and-apps/organization.html">Organization</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../orgs-and-apps/application.html">Application</a></li> |
| </ul> |
| <p class="caption"><span class="caption-text">API Reference</span></p> |
| <ul> |
| <li class="toctree-l1"><a class="reference internal" href="../rest-endpoints/api-docs.html">Methods</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../rest-endpoints/api-docs.html#models">Models</a></li> |
| </ul> |
| <p class="caption"><span class="caption-text">Client SDKs</span></p> |
| <ul> |
| <li class="toctree-l1"><a class="reference internal" href="../sdks/tbd.html">COMING SOON...</a></li> |
| </ul> |
| <p class="caption"><span class="caption-text">Installing the Stack</span></p> |
| <ul> |
| <li class="toctree-l1"><a class="reference internal" href="../installation/ug1-deploy-to-tomcat.html">Usegrid 1: Deploying to Tomcat</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../installation/ug1-launcher-quick-start.html">Usegrid 1: Launcher Quick-start</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../installation/ug2-deploy-to-tomcat.html">Usergrid 2: Deploy to Tomcat</a></li> |
| </ul> |
| <p class="caption"><span class="caption-text">More about Usergrid</span></p> |
| <ul> |
| <li class="toctree-l1"><a class="reference internal" href="../reference/presos-and-videos.html">Presentations & Videos</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../reference/contribute-code.html">How to Contribute Code & Docs</a></li> |
| </ul> |
| |
| |
| |
| </div> |
| |
| </nav> |
| |
| <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"> |
| |
| |
| <nav class="wy-nav-top" role="navigation" aria-label="top navigation"> |
| <i data-toggle="wy-nav-top" class="fa fa-bars"></i> |
| <a href="../index.html">Apache Usergrid</a> |
| </nav> |
| |
| |
| |
| <div class="wy-nav-content"> |
| <div class="rst-content"> |
| <div role="navigation" aria-label="breadcrumbs navigation"> |
| <ul class="wy-breadcrumbs"> |
| <li><a href="../index.html">Docs</a> »</li> |
| |
| <li>Query Language</li> |
| <li class="wy-breadcrumbs-aside"> |
| |
| |
| <a href="../_sources/data-queries/query-language.txt" rel="nofollow"> View page source</a> |
| |
| |
| </li> |
| </ul> |
| <hr/> |
| </div> |
| <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article"> |
| <div itemprop="articleBody"> |
| |
| <div class="section" id="query-language"> |
| <h1>Query Language<a class="headerlink" href="#query-language" title="Permalink to this headline">¶</a></h1> |
| <blockquote> |
| <div>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></blockquote> |
| <p>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:</p> |
| <div class="highlight-python"><div class="highlight"><pre>/restaurants?ql=select * where name contains 'diner' order by name asc |
| </pre></div> |
| </div> |
| <div class="section" id="basic-syntax"> |
| <h2>Basic syntax<a class="headerlink" href="#basic-syntax" title="Permalink to this headline">¶</a></h2> |
| <p>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.</p> |
| <p>To retrieve items from a collection, you would use a syntax such as the |
| following:</p> |
| <div class="highlight-python"><div class="highlight"><pre>/<collection>?ql=<query_statement> |
| </pre></div> |
| </div> |
| <p>In the following example, the query is retrieving all users whose name |
| is Gladys Kravitz.</p> |
| <div class="highlight-python"><div class="highlight"><pre>/users?ql=select * where name = 'Gladys Kravitz' |
| </pre></div> |
| </div> |
| <p>The following example selects all items except those that have an a |
| property value of 5:</p> |
| <div class="highlight-python"><div class="highlight"><pre>/items?ql=select * where NOT a = 5 |
| </pre></div> |
| </div> |
| <p>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:</p> |
| <div class="highlight-python"><div class="highlight"><pre>/items?ql=NOT a = 5 |
| </pre></div> |
| </div> |
| <p>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.</p> |
| <p>The syntax of Apache Usergrid queries only <em>resembles</em> SQL to make |
| queries familiar and easier to write. However, the language isn’t SQL. |
| Only the syntax items documented here are supported.</p> |
| </div> |
| <div class="section" id="supported-operators"> |
| <h2>Supported operators<a class="headerlink" href="#supported-operators" title="Permalink to this headline">¶</a></h2> |
| <p>Comparisons</p> |
| <ul class="simple"> |
| <li>Less than <code class="docutils literal"><span class="pre"><</span></code> or <code class="docutils literal"><span class="pre">lt</span></code></li> |
| <li>Less than or equal <code class="docutils literal"><span class="pre"><=</span></code> or <code class="docutils literal"><span class="pre">lte</span></code></li> |
| <li>Equal <code class="docutils literal"><span class="pre">=</span></code> or <code class="docutils literal"><span class="pre">eq</span></code></li> |
| <li>Greater than or equal <code class="docutils literal"><span class="pre">>=</span></code> or <code class="docutils literal"><span class="pre">gte</span></code></li> |
| <li>Greater than <code class="docutils literal"><span class="pre">></span></code> or <code class="docutils literal"><span class="pre">gt</span></code></li> |
| <li>Not equal <code class="docutils literal"><span class="pre">NOT</span></code></li> |
| </ul> |
| <p>Logical operations</p> |
| <ul class="simple"> |
| <li>Intersection of results <code class="docutils literal"><span class="pre">and</span></code></li> |
| <li>Union of results <code class="docutils literal"><span class="pre">or</span></code></li> |
| <li>Subtraction of results <code class="docutils literal"><span class="pre">not</span></code></li> |
| </ul> |
| </div> |
| <div class="section" id="query-response-format"> |
| <h2>Query Response Format<a class="headerlink" href="#query-response-format" title="Permalink to this headline">¶</a></h2> |
| <p>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.</p> |
| <p>So for the following query:</p> |
| <div class="highlight-python"><div class="highlight"><pre>/users?ql=select * where name = ‘Gladys Kravitz’ |
| </pre></div> |
| </div> |
| <p>...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.</p> |
| <p>Here, the query is asking for whole entities in the users collection. |
| Data corresponding to the response is captured in the response’s |
| <code class="docutils literal"><span class="pre">entities</span></code> 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.</p> |
| <div class="code json highlight-python"><div class="highlight"><pre><span class="p">{</span> |
| <span class="s">"action"</span> <span class="p">:</span> <span class="s">"get"</span><span class="p">,</span> |
| <span class="s">"application"</span> <span class="p">:</span> <span class="s">"8272c9b0-d86a-11e2-92e2-cdf1ce04c1c0"</span><span class="p">,</span> |
| <span class="s">"params"</span> <span class="p">:</span> <span class="p">{</span> |
| <span class="s">"ql"</span> <span class="p">:</span> <span class="p">[</span> <span class="s">"select * where name = 'Gladys Kravitz'"</span> <span class="p">]</span> |
| <span class="p">},</span> |
| <span class="s">"path"</span> <span class="p">:</span> <span class="s">"/users"</span><span class="p">,</span> |
| <span class="s">"uri"</span> <span class="p">:</span> <span class="s">"http://api.usergrid.com/myorg/myapp/users"</span><span class="p">,</span> |
| <span class="s">"entities"</span> <span class="p">:</span> <span class="p">[</span> <span class="p">{</span> |
| <span class="s">"uuid"</span> <span class="p">:</span> <span class="s">"d0d7d0ba-e97b-11e2-8cef-411c466c4f2c"</span><span class="p">,</span> |
| <span class="s">"type"</span> <span class="p">:</span> <span class="s">"user"</span><span class="p">,</span> |
| <span class="s">"name"</span> <span class="p">:</span> <span class="s">"Gladys Kravitz"</span><span class="p">,</span> |
| <span class="s">"created"</span> <span class="p">:</span> <span class="mi">1373472876859</span><span class="p">,</span> |
| <span class="s">"modified"</span> <span class="p">:</span> <span class="mi">1373472876859</span><span class="p">,</span> |
| <span class="s">"username"</span> <span class="p">:</span> <span class="s">"gladys"</span><span class="p">,</span> |
| <span class="s">"email"</span> <span class="p">:</span> <span class="s">"gladys@example.com"</span><span class="p">,</span> |
| <span class="s">"activated"</span> <span class="p">:</span> <span class="n">true</span><span class="p">,</span> |
| <span class="s">"picture"</span> <span class="p">:</span> <span class="s">"http://www.gravatar.com/avatar/20c57d4f41cf51f2db44165eb058b3b2"</span><span class="p">,</span> |
| <span class="s">"metadata"</span> <span class="p">:</span> <span class="p">{</span> |
| <span class="s">"path"</span> <span class="p">:</span> <span class="s">"/users/d0d7d0ba-e97b-11e2-8cef-411c466c4f2c"</span><span class="p">,</span> |
| <span class="s">"sets"</span> <span class="p">:</span> <span class="p">{</span> |
| <span class="s">"rolenames"</span> <span class="p">:</span> <span class="s">"/users/d0d7d0ba-e97b-11e2-8cef-411c466c4f2c/rolenames"</span><span class="p">,</span> |
| <span class="s">"permissions"</span> <span class="p">:</span> <span class="s">"/users/d0d7d0ba-e97b-11e2-8cef-411c466c4f2c/permissions"</span> |
| <span class="p">},</span> |
| <span class="s">"connections"</span> <span class="p">:</span> <span class="p">{</span> |
| <span class="s">"firstname"</span> <span class="p">:</span> <span class="s">"/users/d0d7d0ba-e97b-11e2-8cef-411c466c4f2c/firstname"</span><span class="p">,</span> |
| <span class="s">"lastname"</span> <span class="p">:</span> <span class="s">"/users/d0d7d0ba-e97b-11e2-8cef-411c466c4f2c/lastname"</span> |
| <span class="p">},</span> |
| <span class="s">"collections"</span> <span class="p">:</span> <span class="p">{</span> |
| <span class="s">"activities"</span> <span class="p">:</span> <span class="s">"/users/d0d7d0ba-e97b-11e2-8cef-411c466c4f2c/activities"</span><span class="p">,</span> |
| <span class="s">"devices"</span> <span class="p">:</span> <span class="s">"/users/d0d7d0ba-e97b-11e2-8cef-411c466c4f2c/devices"</span><span class="p">,</span> |
| <span class="s">"feed"</span> <span class="p">:</span> <span class="s">"/users/d0d7d0ba-e97b-11e2-8cef-411c466c4f2c/feed"</span><span class="p">,</span> |
| <span class="s">"groups"</span> <span class="p">:</span> <span class="s">"/users/d0d7d0ba-e97b-11e2-8cef-411c466c4f2c/groups"</span><span class="p">,</span> |
| <span class="s">"roles"</span> <span class="p">:</span> <span class="s">"/users/d0d7d0ba-e97b-11e2-8cef-411c466c4f2c/roles"</span><span class="p">,</span> |
| <span class="s">"following"</span> <span class="p">:</span> <span class="s">"/users/d0d7d0ba-e97b-11e2-8cef-411c466c4f2c/following"</span><span class="p">,</span> |
| <span class="s">"followers"</span> <span class="p">:</span> <span class="s">"/users/d0d7d0ba-e97b-11e2-8cef-411c466c4f2c/followers"</span> |
| <span class="p">}</span> |
| <span class="p">}</span> |
| <span class="p">}</span> <span class="p">],</span> |
| <span class="s">"timestamp"</span> <span class="p">:</span> <span class="mi">1374694196061</span><span class="p">,</span> |
| <span class="s">"duration"</span> <span class="p">:</span> <span class="mi">48</span><span class="p">,</span> |
| <span class="s">"organization"</span> <span class="p">:</span> <span class="s">"myorg"</span><span class="p">,</span> |
| <span class="s">"applicationName"</span> <span class="p">:</span> <span class="s">"myapp"</span><span class="p">,</span> |
| <span class="s">"count"</span> <span class="p">:</span> <span class="mi">1</span> |
| <span class="p">}</span> |
| </pre></div> |
| </div> |
| <p>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):</p> |
| <div class="highlight-python"><div class="highlight"><pre>/users?ql=select username,name where name=’Gladys Kravitz’ |
| </pre></div> |
| </div> |
| <p>In the response JSON from this query, the return value is specified as |
| the property of the <code class="docutils literal"><span class="pre">list</span></code> 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).</p> |
| <div class="highlight-python"><div class="highlight"><pre><span class="p">{</span> |
| <span class="s">"action"</span> <span class="p">:</span> <span class="s">"get"</span><span class="p">,</span> |
| <span class="s">"application"</span> <span class="p">:</span> <span class="s">"8272c9b0-d86a-11e2-92e2-cdf1ce04c1c0"</span><span class="p">,</span> |
| <span class="s">"params"</span> <span class="p">:</span> <span class="p">{</span> |
| <span class="s">"ql"</span> <span class="p">:</span> <span class="p">[</span> <span class="s">"select username,name where name='Gladys Kravitz'"</span> <span class="p">]</span> |
| <span class="p">},</span> |
| <span class="s">"path"</span> <span class="p">:</span> <span class="s">"/users"</span><span class="p">,</span> |
| <span class="s">"uri"</span> <span class="p">:</span> <span class="s">"http://api.usergrid.com/myorg/myapp/users"</span><span class="p">,</span> |
| <span class="s">"list"</span> <span class="p">:</span> <span class="p">[</span> <span class="p">[</span> <span class="s">"gladys"</span><span class="p">,</span> <span class="s">"Gladys Kravitz"</span> <span class="p">]</span> <span class="p">],</span> |
| <span class="s">"timestamp"</span> <span class="p">:</span> <span class="mi">1374697463190</span><span class="p">,</span> |
| <span class="s">"duration"</span> <span class="p">:</span> <span class="mi">25</span><span class="p">,</span> |
| <span class="s">"organization"</span> <span class="p">:</span> <span class="s">"myorg"</span><span class="p">,</span> |
| <span class="s">"applicationName"</span> <span class="p">:</span> <span class="s">"myapp"</span><span class="p">,</span> |
| <span class="s">"count"</span> <span class="p">:</span> <span class="mi">1</span> |
| <span class="p">}</span> |
| </pre></div> |
| </div> |
| </div> |
| <div class="section" id="data-types-supported-in-queries"> |
| <h2>Data types supported in queries<a class="headerlink" href="#data-types-supported-in-queries" title="Permalink to this headline">¶</a></h2> |
| <p>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 <a class="reference external" href="/default-data-entities">Default Data |
| Entities</a>.)</p> |
| <p>For example, in the default entity <code class="docutils literal"><span class="pre">User</span></code>, the <code class="docutils literal"><span class="pre">name</span></code> property is |
| stored as a <code class="docutils literal"><span class="pre">string</span></code>, the created date as a <code class="docutils literal"><span class="pre">long</span></code>, 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.</p> |
| <p>So imagine you define an entity with a <code class="docutils literal"><span class="pre">price</span></code> property whose value |
| might be <code class="docutils literal"><span class="pre">100.00</span></code>. Querying for <code class="docutils literal"><span class="pre">100</span></code> will return no results even if |
| there are occurrences of <code class="docutils literal"><span class="pre">100.00</span></code> as <code class="docutils literal"><span class="pre">price</span></code> values in your data |
| set. That’s because the database expected a decimal-delimited <code class="docutils literal"><span class="pre">float</span></code> |
| value in your query.</p> |
| <table border="1" class="docutils"> |
| <colgroup> |
| <col width="6%" /> |
| <col width="22%" /> |
| <col width="73%" /> |
| </colgroup> |
| <thead valign="bottom"> |
| <tr class="row-odd"><th class="head">Data Type</th> |
| <th class="head">Examples</th> |
| <th class="head">Notes</th> |
| </tr> |
| </thead> |
| <tbody valign="top"> |
| <tr class="row-even"><td><code class="docutils literal"><span class="pre">string</span></code></td> |
| <td><code class="docutils literal"><span class="pre">'value'</span></code>, <code class="docutils literal"><span class="pre">unicode</span> <span class="pre">'\uFFFF'</span></code>, <code class="docutils literal"><span class="pre">octal</span> <span class="pre">'\0707'</span></code></td> |
| <td>true | false</td> |
| </tr> |
| <tr class="row-odd"><td><code class="docutils literal"><span class="pre">long</span></code></td> |
| <td>1357412326021</td> |
| <td>Timestamps are typically stored as <code class="docutils literal"><span class="pre">long</span></code> values.</td> |
| </tr> |
| <tr class="row-even"><td><code class="docutils literal"><span class="pre">float</span></code></td> |
| <td>10.1, -10.1, 10e10, 10e-10, 10E10, 10e-10</td> |
| <td>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 class="row-odd"><td><code class="docutils literal"><span class="pre">boolean</span></code></td> |
| <td>true | false</td> |
| <td> </td> |
| </tr> |
| <tr class="row-even"><td><code class="docutils literal"><span class="pre">UUID</span></code></td> |
| <td>ee912c4b-5769-11e2-924d-02e81ac5a17b</td> |
| <td>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</td> |
| </tr> |
| </tbody> |
| </table> |
| <p><code class="docutils literal"><span class="pre">object</span></code> For a JSON object like this one:</p> |
| <div class="highlight-python"><div class="highlight"><pre><span class="p">{</span> |
| <span class="s">"items"</span><span class="p">:[</span> |
| <span class="p">{</span><span class="s">"name"</span><span class="p">:</span><span class="s">"rocks"</span><span class="p">},</span> |
| <span class="p">{</span><span class="s">"name"</span><span class="p">:</span><span class="s">"boats"</span><span class="p">}</span> |
| <span class="p">]</span> |
| <span class="p">}</span> |
| </pre></div> |
| </div> |
| <p>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.</p> |
| </div> |
| <div class="section" id="retrieving-values-for-multiple-properties"> |
| <h2>Retrieving values for multiple properties<a class="headerlink" href="#retrieving-values-for-multiple-properties" title="Permalink to this headline">¶</a></h2> |
| <p>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.</p> |
| <p>For example, the following request returns the address and phone number |
| of users whose name is Gladys Kravitz:</p> |
| <div class="highlight-python"><div class="highlight"><pre>/users?ql=select address,phone_number where name = 'Gladys Kravitz' |
| </pre></div> |
| </div> |
| </div> |
| <div class="section" id="querying-for-the-contents-of-text"> |
| <h2>Querying for the contents of text<a class="headerlink" href="#querying-for-the-contents-of-text" title="Permalink to this headline">¶</a></h2> |
| <p>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.</p> |
| <p>For example, the following query selects all restaurants with the word |
| <code class="docutils literal"><span class="pre">diner</span></code> in the name:</p> |
| <div class="highlight-python"><div class="highlight"><pre>/restaurants?ql=select * where name contains 'diner' |
| </pre></div> |
| </div> |
| <p><strong>Note:</strong> Not all string properties of the default entities are indexed |
| for searching. This includes the <code class="docutils literal"><span class="pre">User</span></code> entity’s <code class="docutils literal"><span class="pre">username</span></code> |
| property.</p> |
| <p>This will return all users whose name property contains the word |
| ‘Kravitz’</p> |
| <div class="highlight-python"><div class="highlight"><pre>/users?ql=select * where name contains 'Kravitz' |
| </pre></div> |
| </div> |
| <p>This will return all users whose name property contains a word beginning |
| with ‘Krav’</p> |
| <div class="highlight-python"><div class="highlight"><pre>/users?ql=select * where name contains 'Krav*' |
| </pre></div> |
| </div> |
| <p>This will return all users whose name is exactly ‘Gladys Kravitz’</p> |
| <div class="highlight-python"><div class="highlight"><pre>/users?ql=select * where name = 'Gladys Kravitz' |
| </pre></div> |
| </div> |
| </div> |
| <div class="section" id="sorting-results"> |
| <h2>Sorting results<a class="headerlink" href="#sorting-results" title="Permalink to this headline">¶</a></h2> |
| <p>You can return query results that are sorted in the order you specify. |
| Use the <code class="docutils literal"><span class="pre">order</span> <span class="pre">by</span></code> 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 <code class="docutils literal"><span class="pre">order</span> <span class="pre">by</span> <span class="pre"><property_name></span> <span class="pre">asc</span> <span class="pre">|</span> <span class="pre">desc</span></code></p> |
| <p>The following table includes a few examples:</p> |
| <div class="highlight-python"><div class="highlight"><pre>/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 |
| </pre></div> |
| </div> |
| </div> |
| <div class="section" id="geoqueries"> |
| <h2>Geoqueries<a class="headerlink" href="#geoqueries" title="Permalink to this headline">¶</a></h2> |
| <p>Many of today’s apps are enhanced by the use of <em>geolocation</em>, wireless |
| detection of the physical location of a remote device. These apps are |
| said to be <em>geolocation-aware</em> 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.</p> |
| <p>Usergrid support geolocation on any entity, both built in (e.g., users, |
| groups) and user defined.</p> |
| <p>To add a location to any entity, include the following member to the |
| JSON in a POST or PUT call:</p> |
| <div class="highlight-python"><div class="highlight"><pre>"location": { |
| "latitude": 37.779632, |
| "longitude": -122.395131 |
| } |
| </pre></div> |
| </div> |
| <p>For example, to store a listing of restaurants and their locations, |
| start by creating a collection called restaurants:</p> |
| <div class="highlight-python"><div class="highlight"><pre>POST https://api.usergrid.com/org_name/app_name/restaurants |
| </pre></div> |
| </div> |
| <p>Next, add a new entity to the collection:</p> |
| <div class="highlight-python"><div class="highlight"><pre>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 |
| } |
| } |
| </pre></div> |
| </div> |
| <p>This creates a new restaurant entity called “Rockadero” with the |
| longitude and latitude included as part of the object.</p> |
| <p>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:</p> |
| <div class="highlight-python"><div class="highlight"><pre>location within <distance in meters> of <latitude>, <longitude> |
| </pre></div> |
| </div> |
| <p>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:</p> |
| <div class="highlight-python"><div class="highlight"><pre>GET https://api.usergrid.com/org_name/app_name/restaurants?ql=location within 16093 of 37.776753, -122.407846 |
| </pre></div> |
| </div> |
| </div> |
| <div class="section" id="managing-large-sets-of-results"> |
| <h2>Managing large sets of results<a class="headerlink" href="#managing-large-sets-of-results" title="Permalink to this headline">¶</a></h2> |
| <p>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.</p> |
| <p>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.</p> |
| <p>You would use the following parameters in your query:</p> |
| <table border="1" class="docutils"> |
| <colgroup> |
| <col width="33%" /> |
| <col width="33%" /> |
| <col width="33%" /> |
| </colgroup> |
| <thead valign="bottom"> |
| <tr class="row-odd"><th class="head">Parameter</th> |
| <th class="head">Type</th> |
| <th class="head">Description</th> |
| </tr> |
| </thead> |
| <tbody valign="top"> |
| <tr class="row-even"><td><code class="docutils literal"><span class="pre">limit</span></code></td> |
| <td>integer</td> |
| <td><p class="first">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>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’:</p> |
| <div class="highlight-python"><div class="highlight"><pre>/books?ql=author = |
| </pre></div> |
| </div> |
| <p>‘Hemingway’&limit=100</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> |
| <div class="highlight-python"><div class="highlight"><pre>/books?limit=100 |
| </pre></div> |
| </div> |
| <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> |
| <div class="highlight-python"><div class="highlight"><pre>DELETE /books?limit |
| </pre></div> |
| </div> |
| <p>=1000</p> |
| <p class="last">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> |
| <tr class="row-odd"><td><code class="docutils literal"><span class="pre">cursor</span></code></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> |
| </tbody> |
| </table> |
| <p>For example:</p> |
| <p>Select all users whose name starts with fred, and returns the first 50 |
| results:</p> |
| <div class="highlight-python"><div class="highlight"><pre>/users?ql=select * where name = 'fred*'&limit=50 |
| </pre></div> |
| </div> |
| <p>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:</p> |
| <div class="highlight-python"><div class="highlight"><pre>/users?ql=select * where name = 'fred*'&limit=50&cursor=LTIxNDg0NDUxNDpnR2tBQVFFQWdITUFDWFJ2YlM1emJXbDBhQUNBZFFBUUQyMVZneExfRWVLRlV3TG9Hc1doZXdDQWRRQVFIYVdjb0JwREVlS1VCd0xvR3NWT0JRQQ |
| </pre></div> |
| </div> |
| </div> |
| </div> |
| |
| |
| </div> |
| </div> |
| <footer> |
| |
| |
| <hr/> |
| |
| <div role="contentinfo"> |
| <p> |
| © Copyright 2013-2015, Apache Usergrid. |
| |
| </p> |
| </div> |
| Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>. |
| |
| </footer> |
| |
| </div> |
| </div> |
| |
| </section> |
| |
| </div> |
| |
| |
| |
| |
| |
| <script type="text/javascript"> |
| var DOCUMENTATION_OPTIONS = { |
| URL_ROOT:'../', |
| VERSION:'1.0', |
| COLLAPSE_INDEX:false, |
| FILE_SUFFIX:'.html', |
| HAS_SOURCE: true |
| }; |
| </script> |
| <script type="text/javascript" src="../_static/jquery.js"></script> |
| <script type="text/javascript" src="../_static/underscore.js"></script> |
| <script type="text/javascript" src="../_static/doctools.js"></script> |
| |
| |
| |
| |
| |
| <script type="text/javascript" src="../_static/js/theme.js"></script> |
| |
| |
| |
| |
| <script type="text/javascript"> |
| jQuery(function () { |
| SphinxRtdTheme.StickyNav.enable(); |
| }); |
| </script> |
| |
| |
| </body> |
| </html> |
