Google Git
Sign in
apache/usergrid/refs/heads/master/./content/docs/data-storage/collections.html
blob: 1a7dedc7a86f35e37464069d3c663515539d1cb7 [file] [log] [blame]
<!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>Collections &mdash; Apache Usergrid 2.x documentation</title>
<link rel="stylesheet" href="../_static/css/theme.css" type="text/css" />
<link rel="top" title="Apache Usergrid 2.x documentation" href="../index.html"/>
<link rel="next" title="Entities" href="entities.html"/>
<link rel="prev" title="Data Store Best Practices" href="optimizing-access.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">
2.x
</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">Getting Started</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../introduction/overview.html">Getting Started</a></li>
<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">Using Usergrid</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../using-usergrid/creating-account.html">Creating a Usergrid Account</a></li>
<li class="toctree-l1"><a class="reference internal" href="../using-usergrid/creating-a-new-application.html">Creating a new application</a></li>
<li class="toctree-l1"><a class="reference internal" href="../using-usergrid/using-a-sandbox-app.html">Using a Sandbox Application</a></li>
<li class="toctree-l1"><a class="reference internal" href="../using-usergrid/using-the-api.html">Using the API</a></li>
</ul>
<p class="caption"><span class="caption-text">Data Storage</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="data-store-dbms.html">The Usergrid Data Store</a></li>
<li class="toctree-l1"><a class="reference internal" href="optimizing-access.html">Data Store Best Practices</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="">Collections</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#creating-collections">Creating Collections</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#creating-a-collection">Creating a collection</a></li>
<li class="toctree-l3"><a class="reference internal" href="#request-syntax">Request Syntax</a></li>
<li class="toctree-l3"><a class="reference internal" href="#example-request-response">Example Request/Response</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#collection-settings">Collection Settings</a></li>
<li class="toctree-l2"><a class="reference internal" href="#setting-up-selective-indexing-via-collection-settings">Setting up Selective Indexing via Collection Settings</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#specifying-a-schema-for-a-collection">Specifying a Schema for a Collection</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#example-turn-off-indexing-for-a-collection">Example: Turn off Indexing for a Collection</a></li>
<li class="toctree-l4"><a class="reference internal" href="#example-index-only-one-field-of-a-collection">Example: Index only one field of a Collection</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#retrieving-collections">Retrieving Collections</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#retrieving-sets-of-entities-from-a-collection">Retrieving sets of entities from a collection</a></li>
<li class="toctree-l3"><a class="reference internal" href="#id5">Request Syntax</a></li>
<li class="toctree-l3"><a class="reference internal" href="#id6">Example Request/Response</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#updating-collections">Updating Collections</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#batch-updating-entities-in-a-collection">Batch updating entities in a collection</a></li>
<li class="toctree-l3"><a class="reference internal" href="#id7">Request Syntax</a></li>
<li class="toctree-l3"><a class="reference internal" href="#id8">Example Request/Response</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#deleting-collections">Deleting Collections</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#batch-deleting-entities-in-a-collection">Batch deleting entities in a collection</a></li>
<li class="toctree-l3"><a class="reference internal" href="#id9">Request Syntax</a></li>
<li class="toctree-l3"><a class="reference internal" href="#id10">Example Request/Response</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="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="../data-queries/querying-your-data.html">Querying your data</a></li>
<li class="toctree-l1"><a class="reference internal" href="../data-queries/query-parameters.html">Query parameters &amp; clauses</a></li>
<li class="toctree-l1"><a class="reference internal" href="../data-queries/operators-and-types.html">Query operators &amp; data types</a></li>
<li class="toctree-l1"><a class="reference internal" href="../data-queries/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">Push Notifications</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../push-notifications/overview.html">Push notifications overview</a></li>
<li class="toctree-l1"><a class="reference internal" href="../push-notifications/adding-push-support.html">Adding push notifications support</a></li>
<li class="toctree-l1"><a class="reference internal" href="../push-notifications/getting-started.html">Getting started with push notifications</a></li>
<li class="toctree-l1"><a class="reference internal" href="../push-notifications/tutorial.html">Tutorial: Push notifications sample app</a></li>
<li class="toctree-l1"><a class="reference internal" href="../push-notifications/registering.html">Registering with a notification service</a></li>
<li class="toctree-l1"><a class="reference internal" href="../push-notifications/creating-notifiers.html">Creating notifiers</a></li>
<li class="toctree-l1"><a class="reference internal" href="../push-notifications/managing-users-and-devices.html">Managing users and devices</a></li>
<li class="toctree-l1"><a class="reference internal" href="../push-notifications/creating-and-managing-notifications.html">Creating and managing notifications</a></li>
<li class="toctree-l1"><a class="reference internal" href="../push-notifications/troubleshooting.html">Troubleshooting</a></li>
</ul>
<p class="caption"><span class="caption-text">Security &amp; Authentication</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../security-and-auth/app-security.html">Security &amp; 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/using-roles.html">Using roles</a></li>
<li class="toctree-l1"><a class="reference internal" href="../security-and-auth/authenticating-users-and-application-clients.html">Authenticating users &amp; 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 &amp; Social Graph</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../user-management/user-management.html">User management &amp; 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 &amp; Files</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../assets-and-files/uploading-assets.html">Uploading assets</a></li>
<li class="toctree-l1"><a class="reference internal" href="../assets-and-files/retrieving-assets.html">Retrieving assets</a></li>
<li class="toctree-l1"><a class="reference internal" href="../assets-and-files/folders.html">Folders</a></li>
</ul>
<p class="caption"><span class="caption-text">Counters &amp; Events</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../counters-and-events/events-and-counters.html">Counters &amp; events</a></li>
<li class="toctree-l1"><a class="reference internal" href="../counters-and-events/creating-and-incrementing-counters.html">Creating &amp; 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 &amp; Applications</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../orgs-and-apps/managing.html">Organization &amp; 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>
<li class="toctree-l1"><a class="reference internal" href="../orgs-and-apps/admin-user.html">Admin user</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>
<li class="toctree-l1"><a class="reference internal" href="../rest-endpoints/api-docs.html#sub-types">Sub-Types</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 Usergrid</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../installation/deployment-guide.html">Usergrid 2.1.0 Deployment Guide</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 &amp; Videos</a></li>
<li class="toctree-l1"><a class="reference internal" href="../reference/contribute-code.html">How to Contribute Code &amp; Docs</a></li>
</ul>
</div>
&nbsp;
</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> &raquo;</li>
<li>Collections</li>
<li class="wy-breadcrumbs-aside">
<a href="../_sources/data-storage/collections.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="collections">
<h1>Collections<a class="headerlink" href="#collections" title="Permalink to this headline">ΒΆ</a></h1>
<div class="section" id="creating-collections">
<h2>Creating Collections<a class="headerlink" href="#creating-collections" title="Permalink to this headline">ΒΆ</a></h2>
<p>This article describes how to create collections in Advanced Usergrid.
All entities are automatically associated with a corresponding
collection based on the type property of the entity. You may create
empty collections if you wish, but creating an entity of a new type will
automatically create a corresponding collection for you. For example,
creating a new custom &#8220;item&#8221; entity, creates an &#8220;items&#8221; collection.</p>
<p><strong>Note</strong>: Although not shown in the API examples below, you need to
provide a valid access token with each API call. See <a class="reference external" href="../security-and-auth/authenticating-users-and-application-clients.html">Authenticating
users and application
clients</a>
for details.</p>
<div class="section" id="creating-a-collection">
<h3>Creating a collection<a class="headerlink" href="#creating-a-collection" title="Permalink to this headline">ΒΆ</a></h3>
<p>The following example shows how to create an empty collection.
Alternatively, you can create a collection simply by creating a new
entity with a &#8216;type&#8217; property that corresponds to the collection you
wish to create. For more on creating entities, see Creating Custom Data
Entities</p>
</div>
<div class="section" id="request-syntax">
<h3>Request Syntax<a class="headerlink" href="#request-syntax" title="Permalink to this headline">ΒΆ</a></h3>
<div class="highlight-python"><div class="highlight"><pre>curl -X POST https://api.usergrid.com/&lt;org&gt;/&lt;app&gt;/&lt;collection_name&gt;
</pre></div>
</div>
<p>Parameters</p>
<table border="1" class="docutils">
<colgroup>
<col width="31%" />
<col width="69%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Parameter</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>org</td>
<td>Organization UUID or organization name</td>
</tr>
<tr class="row-odd"><td>app</td>
<td>Application UUID or application name</td>
</tr>
<tr class="row-even"><td>collection name</td>
<td>Name of the collection to create.</td>
</tr>
</tbody>
</table>
<p>If the provided value is not a plural word, Usergrid will pluralize it.
For example, providing &#8216;item&#8217; will create a collection named &#8216;items&#8217; but
providing &#8216;items&#8217; will not create &#8216;itemses&#8217;.</p>
</div>
<div class="section" id="example-request-response">
<h3>Example Request/Response<a class="headerlink" href="#example-request-response" title="Permalink to this headline">ΒΆ</a></h3>
<p>Request:</p>
<div class="highlight-python"><div class="highlight"><pre>curl -X POST &quot;https://api.usergrid.com/your-org/your-app/item&quot;
</pre></div>
</div>
<p>Response:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="p">{</span>
<span class="s">&quot;action&quot;</span> <span class="p">:</span> <span class="s">&quot;post&quot;</span><span class="p">,</span>
<span class="s">&quot;application&quot;</span> <span class="p">:</span> <span class="s">&quot;f34f4222-a166-11e2-a7f7-02e81adcf3d0&quot;</span><span class="p">,</span>
<span class="s">&quot;params&quot;</span> <span class="p">:</span> <span class="p">{</span> <span class="p">},</span>
<span class="s">&quot;path&quot;</span> <span class="p">:</span> <span class="s">&quot;/items&quot;</span><span class="p">,</span>
<span class="s">&quot;uri&quot;</span> <span class="p">:</span> <span class="s">&quot;http://api.usergrid.com/your-org/your-app/items&quot;</span><span class="p">,</span>
<span class="s">&quot;entities&quot;</span> <span class="p">:</span> <span class="p">[</span> <span class="p">],</span>
<span class="s">&quot;timestamp&quot;</span> <span class="p">:</span> <span class="mi">1378857079220</span><span class="p">,</span>
<span class="s">&quot;duration&quot;</span> <span class="p">:</span> <span class="mi">31</span><span class="p">,</span>
<span class="s">&quot;organization&quot;</span> <span class="p">:</span> <span class="s">&quot;your-org&quot;</span><span class="p">,</span>
<span class="s">&quot;applicationName&quot;</span> <span class="p">:</span> <span class="s">&quot;your-app&quot;</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="collection-settings">
<h2>Collection Settings<a class="headerlink" href="#collection-settings" title="Permalink to this headline">ΒΆ</a></h2>
<p>Usergrid allows you to specify settings for each of your Collections.
Collections may have a *_settings* resource with the following URI
pattern:</p>
<div class="highlight-python"><div class="highlight"><pre>/{org-identifier}/{app-identifier}/{collection-name}/_settings
</pre></div>
</div>
<p>If a Collection does not have a <a href="#id1"><span class="problematic" id="id2">*</span></a>settings resource, then doing an HTTP
GET on that URI will yield the normal Collection resource. For example
here a request and respinse for settings for the Collection &#8220;battles&#8221;,
which does not yet have <a href="#id3"><span class="problematic" id="id4">*</span></a>settigs:</p>
<div class="highlight-python"><div class="highlight"><pre>curl &quot;https//api.usergrid.com/test-organization/settingstest/battles/_settings?access_token=YWM...&quot;
{
&quot;action&quot; : &quot;get&quot;,
&quot;application&quot; : &quot;7fd6c414-2cb6-11e6-8b07-0a669fe1d66e&quot;,
&quot;params&quot; : { },
&quot;path&quot; : &quot;/battles&quot;,
&quot;uri&quot; : &quot;https//api.usergrid.com/test-organization/settingstest/battles&quot;,
&quot;entities&quot; : [ ],
&quot;timestamp&quot; : 1465308535753,
&quot;duration&quot; : 175,
&quot;organization&quot; : &quot;test-organization&quot;,
&quot;applicationName&quot; : &quot;settingstest&quot;
}
</pre></div>
</div>
<p>Once a Collection has a _settings resource, here&#8217;s what it might look
like:</p>
<div class="highlight-python"><div class="highlight"><pre>curl &quot;0:8080/test-organization/settingstest/battles/_settings?access_token=YWM...&quot;
{
&quot;action&quot; : &quot;get&quot;,
&quot;application&quot; : &quot;7fd6c414-2cb6-11e6-8b07-0a669fe1d66e&quot;,
&quot;params&quot; : { },
&quot;path&quot; : &quot;/battles&quot;,
&quot;uri&quot; : &quot;https//api.usergrid.com/test-organization/settingstest/battles&quot;,
&quot;entities&quot; : [ ],
&quot;data&quot; : {
&quot;lastUpdated&quot; : 1465311161543,
&quot;lastReindexed&quot; : 0,
&quot;fields&quot; : &quot;all&quot;,
&quot;region&quot; : &quot;us-east-1&quot;,
&quot;lastUpdateBy&quot; : &quot;super@usergrid.com&quot;
},
&quot;timestamp&quot; : 1465311177535,
&quot;duration&quot; : 6,
&quot;organization&quot; : &quot;test-organization&quot;,
&quot;applicationName&quot; : &quot;settingstest&quot;
}
</pre></div>
</div>
<p>Collection settings are useful for setting up Selective Indexing. Let&#8217;s
discuss that next.</p>
</div>
<div class="section" id="setting-up-selective-indexing-via-collection-settings">
<h2>Setting up Selective Indexing via Collection Settings<a class="headerlink" href="#setting-up-selective-indexing-via-collection-settings" title="Permalink to this headline">ΒΆ</a></h2>
<p>Indexing is expensive and now it can be done selectively.</p>
<p>In the beginning, Usergrid indexed each and every field of an Entity. If
a field was an object, the the fields of that object would also be
indexed. Indexing everything is very convenient because it means you can
query on any field, but indexing everything is expensive in terms of
performance; it slows down Entity creation and update. Indexing
everything is also expensive in terms of storage, it takes up space and
makes puts strain on the system.</p>
<p>Staring with Usegrid 2.1.1, you can specify a &#8220;schema&#8221; for each
Collection. You can tell Usergrid which fields should be indexed or you
can tell Usergrid to completely skip indexing for a collection.</p>
<div class="section" id="specifying-a-schema-for-a-collection">
<h3>Specifying a Schema for a Collection<a class="headerlink" href="#specifying-a-schema-for-a-collection" title="Permalink to this headline">ΒΆ</a></h3>
<p>There are three ways to specify a schema for a Collection. You can
specify that all fields are to be index, you can specify none or you can
specify a list of the fields that should be indexed. You do this by
POSTing or PUTing a _settings resource for the Collection with one
field named &#8220;fields&#8221;.</p>
<p>There are three possible values for &#8220;fields&#8221;:</p>
<table border="1" class="docutils">
<colgroup>
<col width="30%" />
<col width="9%" />
<col width="61%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Fields Setting</th>
<th class="head">Type</th>
<th class="head">Meaning</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>&#8220;fields&#8221;:&#8221;all&#8221;</td>
<td>String</td>
<td>Index all Entity fields</td>
</tr>
<tr class="row-odd"><td>&#8220;fields&#8221;:&#8221;none&#8221;</td>
<td>String</td>
<td>Index no fields; completely skip indexing for this collection.</td>
</tr>
<tr class="row-even"><td>&#8220;fields&#8221;:[&#8220;field1&#8221;, &#8220;field2&#8221;]</td>
<td>Array</td>
<td>Index all fields whose names are listed in the array value.</td>
</tr>
</tbody>
</table>
<div class="section" id="example-turn-off-indexing-for-a-collection">
<h4>Example: Turn off Indexing for a Collection<a class="headerlink" href="#example-turn-off-indexing-for-a-collection" title="Permalink to this headline">ΒΆ</a></h4>
<p>This example shows how you would use curl to set the schema if you want
to turn off indexing for a collection:</p>
<div class="highlight-python"><div class="highlight"><pre>curl -X PUT &quot;0:8080/test-organization/settingstest/_settings?access_token=YWM...&quot; -d &#39;{&quot;fields&quot;:&quot;none&quot;}&#39;
{
&quot;action&quot; : &quot;put&quot;,
&quot;application&quot; : &quot;7fd6c414-2cb6-11e6-8b07-0a669fe1d66e&quot;,
&quot;params&quot; : { },
&quot;path&quot; : &quot;/_settings&quot;,
&quot;uri&quot; : &quot;http://localhost:8080/test-organization/settingstest/_settings&quot;,
&quot;entities&quot; : [ {
&quot;uuid&quot; : &quot;6fc783c6-2cc3-11e6-8fce-0a669fe1d66e&quot;,
&quot;type&quot; : &quot;_setting&quot;,
&quot;created&quot; : 1465312858697,
&quot;modified&quot; : 1465312858697,
&quot;fields&quot; : &quot;none&quot;,
&quot;metadata&quot; : {
&quot;path&quot; : &quot;/_settings/6fc783c6-2cc3-11e6-8fce-0a669fe1d66e&quot;,
&quot;size&quot; : 347
}
} ],
&quot;timestamp&quot; : 1465312858688,
&quot;duration&quot; : 63,
&quot;organization&quot; : &quot;test-organization&quot;,
&quot;applicationName&quot; : &quot;settingstest&quot;
}
</pre></div>
</div>
</div>
<div class="section" id="example-index-only-one-field-of-a-collection">
<h4>Example: Index only one field of a Collection<a class="headerlink" href="#example-index-only-one-field-of-a-collection" title="Permalink to this headline">ΒΆ</a></h4>
<p>This example shows how you would use curl to set the schema if you only
want the &#8220;year&#8221; field to be indexed:</p>
<div class="highlight-python"><div class="highlight"><pre>curl -X PUT &quot;0:8080/test-organization/settingstest/_settings?access_token=YWM...&quot; -d &#39;{&quot;fields&quot;:[&quot;year&quot;]}&#39;
{
&quot;action&quot; : &quot;put&quot;,
&quot;application&quot; : &quot;7fd6c414-2cb6-11e6-8b07-0a669fe1d66e&quot;,
&quot;params&quot; : { },
&quot;path&quot; : &quot;/_settings&quot;,
&quot;uri&quot; : &quot;http://localhost:8080/test-organization/settingstest/_settings&quot;,
&quot;entities&quot; : [ {
&quot;uuid&quot; : &quot;6fc783c6-2cc3-11e6-8fce-0a669fe1d66e&quot;,
&quot;type&quot; : &quot;_setting&quot;,
&quot;created&quot; : 1465312858697,
&quot;modified&quot; : 1465312858697,
&quot;fields&quot; : [ &quot;year&quot; ],
&quot;metadata&quot; : {
&quot;path&quot; : &quot;/_settings/6fc783c6-2cc3-11e6-8fce-0a669fe1d66e&quot;,
&quot;size&quot; : 347
}
} ],
&quot;timestamp&quot; : 1465312858688,
&quot;duration&quot; : 63,
&quot;organization&quot; : &quot;test-organization&quot;,
&quot;applicationName&quot; : &quot;settingstest&quot;
}
</pre></div>
</div>
</div>
</div>
</div>
<div class="section" id="retrieving-collections">
<h2>Retrieving Collections<a class="headerlink" href="#retrieving-collections" title="Permalink to this headline">ΒΆ</a></h2>
<p>This article describes how to retrieve all of the entities in a
collection.</p>
<div class="admonition note"> <p class="first admonition-title"><p>Note</p>
</p> <p class="last"><p>By default, the Usergrid API returns 10 entities per request. For
collections with more than 10 entities, use the returned &#8216;cursor&#8217;
property to retrieve the next 10 entities in the result set. You may
also use the LIMIT parameter in a query string to increase the number of
results returned. For more information on using cursors, see <a class="reference external" href="../data-queries/query-parameters.html">Query
Parameters</a>.</p>
</p></div><p><strong>Note</strong>: Although not shown in the API examples below, you need to
provide a valid access token with each API call. See <a class="reference external" href="../security-and-auth/authenticating-users-and-application-clients.html">Authenticating
users and application
clients</a>
for details.</p>
<div class="section" id="retrieving-sets-of-entities-from-a-collection">
<h3>Retrieving sets of entities from a collection<a class="headerlink" href="#retrieving-sets-of-entities-from-a-collection" title="Permalink to this headline">ΒΆ</a></h3>
</div>
<div class="section" id="id5">
<h3>Request Syntax<a class="headerlink" href="#id5" title="Permalink to this headline">ΒΆ</a></h3>
<div class="highlight-python"><div class="highlight"><pre>curl -X GET https://api.usergrid.com/&lt;org&gt;/&lt;app&gt;/&lt;collection&gt;
</pre></div>
</div>
<p>Parameters</p>
<table border="1" class="docutils">
<colgroup>
<col width="25%" />
<col width="75%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Parameter</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>org</td>
<td>Organization UUID or organization name</td>
</tr>
<tr class="row-odd"><td>app</td>
<td>Application UUID or application name</td>
</tr>
<tr class="row-even"><td>collection</td>
<td>Collection UUID or collection name</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="id6">
<h3>Example Request/Response<a class="headerlink" href="#id6" title="Permalink to this headline">ΒΆ</a></h3>
<p>Request:</p>
<div class="highlight-python"><div class="highlight"><pre>curl -X GET &quot;https://api.usergrid.com/your-org/your-app/items&quot;
</pre></div>
</div>
<p>Response:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="p">{</span>
<span class="s">&quot;action&quot;</span> <span class="p">:</span> <span class="s">&quot;get&quot;</span><span class="p">,</span>
<span class="s">&quot;application&quot;</span> <span class="p">:</span> <span class="s">&quot;f34f4222-a166-11e2-a7f7-02e81adcf3d0&quot;</span><span class="p">,</span>
<span class="s">&quot;params&quot;</span> <span class="p">:</span> <span class="p">{</span> <span class="p">},</span>
<span class="s">&quot;path&quot;</span> <span class="p">:</span> <span class="s">&quot;/items&quot;</span><span class="p">,</span>
<span class="s">&quot;uri&quot;</span> <span class="p">:</span> <span class="s">&quot;http://api.usergrid.com/your-org/your-app/items&quot;</span><span class="p">,</span>
<span class="s">&quot;entities&quot;</span> <span class="p">:</span> <span class="p">[</span> <span class="p">{</span>
<span class="s">&quot;uuid&quot;</span> <span class="p">:</span> <span class="s">&quot;5bb76bca-1657-11e3-903f-9ff6c621a7a4&quot;</span><span class="p">,</span>
<span class="s">&quot;type&quot;</span> <span class="p">:</span> <span class="s">&quot;item&quot;</span><span class="p">,</span>
<span class="s">&quot;name&quot;</span> <span class="p">:</span> <span class="s">&quot;milk&quot;</span><span class="p">,</span>
<span class="s">&quot;created&quot;</span> <span class="p">:</span> <span class="mi">1378405020796</span><span class="p">,</span>
<span class="s">&quot;modified&quot;</span> <span class="p">:</span> <span class="mi">1378405020796</span><span class="p">,</span>
<span class="s">&quot;metadata&quot;</span> <span class="p">:</span> <span class="p">{</span>
<span class="s">&quot;path&quot;</span> <span class="p">:</span> <span class="s">&quot;/items/5bb76bca-1657-11e3-903f-9ff6c621a7a4&quot;</span>
<span class="p">},</span>
<span class="s">&quot;name&quot;</span> <span class="p">:</span> <span class="s">&quot;milk&quot;</span><span class="p">,</span>
<span class="s">&quot;price&quot;</span> <span class="p">:</span> <span class="s">&quot;3.25&quot;</span>
<span class="p">},</span> <span class="p">{</span>
<span class="s">&quot;uuid&quot;</span> <span class="p">:</span> <span class="s">&quot;1a9356ba-1682-11e3-a72a-81581bbaf055&quot;</span><span class="p">,</span>
<span class="s">&quot;type&quot;</span> <span class="p">:</span> <span class="s">&quot;item&quot;</span><span class="p">,</span>
<span class="s">&quot;name&quot;</span> <span class="p">:</span> <span class="s">&quot;bread&quot;</span><span class="p">,</span>
<span class="s">&quot;created&quot;</span> <span class="p">:</span> <span class="mi">1378423379867</span><span class="p">,</span>
<span class="s">&quot;modified&quot;</span> <span class="p">:</span> <span class="mi">1378423379867</span><span class="p">,</span>
<span class="s">&quot;metadata&quot;</span> <span class="p">:</span> <span class="p">{</span>
<span class="s">&quot;path&quot;</span> <span class="p">:</span> <span class="s">&quot;/items/1a9356ba-1682-11e3-a72a-81581bbaf055&quot;</span>
<span class="p">},</span>
<span class="s">&quot;name&quot;</span> <span class="p">:</span> <span class="s">&quot;bread&quot;</span><span class="p">,</span>
<span class="s">&quot;price&quot;</span> <span class="p">:</span> <span class="s">&quot;2.50&quot;</span>
<span class="p">}</span> <span class="p">],</span>
<span class="s">&quot;timestamp&quot;</span> <span class="p">:</span> <span class="mi">1378426821261</span><span class="p">,</span>
<span class="s">&quot;duration&quot;</span> <span class="p">:</span> <span class="mi">35</span><span class="p">,</span>
<span class="s">&quot;organization&quot;</span> <span class="p">:</span> <span class="s">&quot;your-org&quot;</span><span class="p">,</span>
<span class="s">&quot;applicationName&quot;</span> <span class="p">:</span> <span class="s">&quot;your-app&quot;</span><span class="p">,</span>
<span class="s">&quot;count&quot;</span> <span class="p">:</span> <span class="mi">2</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="updating-collections">
<h2>Updating Collections<a class="headerlink" href="#updating-collections" title="Permalink to this headline">ΒΆ</a></h2>
<p>This article describes how to perform batch updates on all entities in a
collection. Batch updates require the use of a query string in the
request, which can either specify all entities in the collection or a
subset of entities for the update to be performed on. For more
information on queries, see Querying your data.</p>
<p><strong>Note</strong>: Although not shown in the API examples below, you need to
provide a valid access token with each API call. See <a class="reference external" href="../security-and-auth/authenticating-users-and-application-clients.html">Authenticating
users and application
clients</a>
for details.</p>
<div class="section" id="batch-updating-entities-in-a-collection">
<h3>Batch updating entities in a collection<a class="headerlink" href="#batch-updating-entities-in-a-collection" title="Permalink to this headline">ΒΆ</a></h3>
</div>
<div class="section" id="id7">
<h3>Request Syntax<a class="headerlink" href="#id7" title="Permalink to this headline">ΒΆ</a></h3>
<div class="highlight-python"><div class="highlight"><pre>curl -X PUT https://api.usergrid.com/&lt;org&gt;/&lt;app&gt;/&lt;collection&gt;/?ql= -d {&lt;property&gt;}
</pre></div>
</div>
<p>Note the empty query string (ql=) appended to the URL.</p>
<p>Parameters</p>
<table border="1" class="docutils">
<colgroup>
<col width="23%" />
<col width="77%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Parameter</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>org</td>
<td>Organization UUID or organization name</td>
</tr>
<tr class="row-odd"><td>app</td>
<td>Application UUID or application name</td>
</tr>
<tr class="row-even"><td>collection</td>
<td>Collection UUID or collection name property</td>
</tr>
</tbody>
</table>
<p>An entity property to be updated, formatted as a key-value pair. For
example:</p>
<div class="highlight-python"><div class="highlight"><pre>{&quot;property_1&quot;:&quot;value_1&quot;, &quot;property_2&quot;:&quot;value_2&quot;,...}
</pre></div>
</div>
</div>
<div class="section" id="id8">
<h3>Example Request/Response<a class="headerlink" href="#id8" title="Permalink to this headline">ΒΆ</a></h3>
<p>Request:</p>
<div class="highlight-python"><div class="highlight"><pre>curl -X PUT https://api.usergrid.com/your-org/your-app/items/?ql= -d &#39;{&quot;availability&quot;:&quot;in-stock&quot;}&#39;
</pre></div>
</div>
<p>Note the empty ?ql= query string.</p>
<p>Response:</p>
<div class="highlight-python"><div class="highlight"><pre>{
&quot;action&quot; : &quot;put&quot;,
&quot;application&quot; : &quot;f34f4222-a166-11e2-a7f7-02e81adcf3d0&quot;,
&quot;params&quot; : {
&quot;ql&quot; : [ &quot;&quot; ]
},
&quot;path&quot; : &quot;/items&quot;,
&quot;uri&quot; : &quot;http://api.usergrid.com/your-org/your-app/items&quot;,
&quot;entities&quot; : [ {
&quot;uuid&quot; : &quot;31847b9a-1a62-11e3-be04-8d05e96f700d&quot;,
&quot;type&quot; : &quot;item&quot;,
&quot;name&quot; : &quot;milk&quot;,
&quot;price&quot; : &quot;3.25&quot;,
&quot;availability&quot; : &quot;in-stock&quot;
&quot;created&quot; : 1378849479113,
&quot;modified&quot; : 1378849567301,
&quot;name&quot; : &quot;milk&quot;,
}, {
&quot;uuid&quot; : &quot;3192ac6a-1a62-11e3-a24f-496ca1d42ce7&quot;,
&quot;type&quot; : &quot;item&quot;,
&quot;name&quot; : &quot;bread&quot;,
&quot;price&quot; : &quot;4.00&quot;,
&quot;availability&quot; : &quot;in-stock&quot;
&quot;created&quot; : 1378849479206,
&quot;modified&quot; : 1378849567351,
&quot;name&quot; : &quot;bread&quot;,
} ],
&quot;timestamp&quot; : 1378849567280,
&quot;duration&quot; : 207,
&quot;organization&quot; : &quot;your-org&quot;,
&quot;applicationName&quot; : &quot;your-app&quot;
}
</pre></div>
</div>
</div>
</div>
<div class="section" id="deleting-collections">
<h2>Deleting Collections<a class="headerlink" href="#deleting-collections" title="Permalink to this headline">ΒΆ</a></h2>
<p>This article describes how to batch delete entities in a collection.
Batch deletes require the use of a query string in the request, which
specifies a subset of entities to be deleted. For more information on
queries, see Querying your data.</p>
<p>Currently, collections cannot be deleted; however, you can delete all of
the entities from a collection.</p>
<p><strong>Note</strong>: Although not shown in the API examples below, you need to
provide a valid access token with each API call. See <a class="reference external" href="../security-and-auth/authenticating-users-and-application-clients.html">Authenticating
users and application
clients</a>
for details.</p>
<div class="section" id="batch-deleting-entities-in-a-collection">
<h3>Batch deleting entities in a collection<a class="headerlink" href="#batch-deleting-entities-in-a-collection" title="Permalink to this headline">ΒΆ</a></h3>
</div>
<div class="section" id="id9">
<h3>Request Syntax<a class="headerlink" href="#id9" title="Permalink to this headline">ΒΆ</a></h3>
<div class="highlight-python"><div class="highlight"><pre>curl -X DELETE https://api.usergrid.com/&lt;org&gt;/&lt;app&gt;/&lt;collection&gt;/?ql=&lt;query&gt;
</pre></div>
</div>
<p>Parameters</p>
<table border="1" class="docutils">
<colgroup>
<col width="18%" />
<col width="83%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Parameter</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>org</td>
<td>Organization UUID or organization name</td>
</tr>
<tr class="row-odd"><td>app</td>
<td>Application UUID or application name</td>
</tr>
<tr class="row-even"><td>collection</td>
<td>Collection UUID or collection name</td>
</tr>
<tr class="row-odd"><td>query</td>
<td>A query string that specifies the subset of entities to delete</td>
</tr>
</tbody>
</table>
<p>(for more information on queries, see Querying your data)</p>
</div>
<div class="section" id="id10">
<h3>Example Request/Response<a class="headerlink" href="#id10" title="Permalink to this headline">ΒΆ</a></h3>
<p>The following example will delete the first 5 entities in a collection.</p>
<p>Request:</p>
<div class="highlight-python"><div class="highlight"><pre>curl -X DELETE https://api.usergrid.com/your-org/your-app/items/?ql=&quot;limit=5&quot;
</pre></div>
</div>
<p>Response:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="p">{</span>
<span class="s">&quot;action&quot;</span> <span class="p">:</span> <span class="s">&quot;delete&quot;</span><span class="p">,</span>
<span class="s">&quot;application&quot;</span> <span class="p">:</span> <span class="s">&quot;f34f4222-a166-11e2-a7f7-02e81adcf3d0&quot;</span><span class="p">,</span>
<span class="s">&quot;params&quot;</span> <span class="p">:</span> <span class="p">{</span>
<span class="s">&quot;ql&quot;</span> <span class="p">:</span> <span class="p">[</span> <span class="s">&quot;&quot;</span> <span class="p">]</span>
<span class="p">},</span>
<span class="s">&quot;path&quot;</span> <span class="p">:</span> <span class="s">&quot;/items&quot;</span><span class="p">,</span>
<span class="s">&quot;uri&quot;</span> <span class="p">:</span> <span class="s">&quot;http://api.usergrid.com/your-org/your-app/items&quot;</span><span class="p">,</span>
<span class="s">&quot;entities&quot;</span> <span class="p">:</span> <span class="p">[</span> <span class="p">{</span>
<span class="s">&quot;uuid&quot;</span> <span class="p">:</span> <span class="s">&quot;53fe3700-0abe-11e3-b1f7-1bd100b8059e&quot;</span><span class="p">,</span>
<span class="s">&quot;type&quot;</span> <span class="p">:</span> <span class="s">&quot;item&quot;</span><span class="p">,</span>
<span class="s">&quot;name&quot;</span> <span class="p">:</span> <span class="s">&quot;milk&quot;</span><span class="p">,</span>
<span class="s">&quot;price&quot;</span> <span class="p">:</span> <span class="s">&quot;3.25&quot;</span><span class="p">,</span>
<span class="s">&quot;created&quot;</span> <span class="p">:</span> <span class="mi">1377129832047</span><span class="p">,</span>
<span class="s">&quot;modified&quot;</span> <span class="p">:</span> <span class="mi">1377129832047</span><span class="p">,</span>
<span class="s">&quot;metadata&quot;</span> <span class="p">:</span> <span class="p">{</span>
<span class="s">&quot;path&quot;</span> <span class="p">:</span> <span class="s">&quot;/items/53fe3700-0abe-11e3-b1f7-1bd100b8059e&quot;</span>
<span class="p">},</span>
<span class="s">&quot;name&quot;</span> <span class="p">:</span> <span class="s">&quot;milk&quot;</span>
<span class="p">},</span> <span class="p">{</span>
<span class="s">&quot;uuid&quot;</span> <span class="p">:</span> <span class="s">&quot;5ae1fa7a-0abe-11e3-89ab-6be0003c809b&quot;</span><span class="p">,</span>
<span class="s">&quot;type&quot;</span> <span class="p">:</span> <span class="s">&quot;item&quot;</span><span class="p">,</span>
<span class="s">&quot;name&quot;</span> <span class="p">:</span> <span class="s">&quot;bread&quot;</span><span class="p">,</span>
<span class="s">&quot;price&quot;</span> <span class="p">:</span> <span class="s">&quot;4.00&quot;</span><span class="p">,</span>
<span class="s">&quot;created&quot;</span> <span class="p">:</span> <span class="mi">1377129843607</span><span class="p">,</span>
<span class="s">&quot;modified&quot;</span> <span class="p">:</span> <span class="mi">1377129843607</span><span class="p">,</span>
<span class="s">&quot;metadata&quot;</span> <span class="p">:</span> <span class="p">{</span>
<span class="s">&quot;path&quot;</span> <span class="p">:</span> <span class="s">&quot;/items/5ae1fa7a-0abe-11e3-89ab-6be0003c809b&quot;</span>
<span class="p">},</span>
<span class="s">&quot;name&quot;</span> <span class="p">:</span> <span class="s">&quot;bread&quot;</span>
<span class="p">}</span> <span class="p">],</span>
<span class="s">&quot;timestamp&quot;</span> <span class="p">:</span> <span class="mi">1378848117272</span><span class="p">,</span>
<span class="s">&quot;duration&quot;</span> <span class="p">:</span> <span class="mi">12275</span><span class="p">,</span>
<span class="s">&quot;organization&quot;</span> <span class="p">:</span> <span class="s">&quot;your-org&quot;</span><span class="p">,</span>
<span class="s">&quot;applicationName&quot;</span> <span class="p">:</span> <span class="s">&quot;your-app&quot;</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
</div>
</div>
</div>
</div>
<footer>
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
<a href="entities.html" class="btn btn-neutral float-right" title="Entities" accesskey="n">Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="optimizing-access.html" class="btn btn-neutral" title="Data Store Best Practices" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous</a>
</div>
<hr/>
<div role="contentinfo">
<p>
&copy; 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:'2.x',
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>