query.html

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <title>JSDoc: Module: datastore/query</title>

    <script src="scripts/prettify/prettify.js"> </script>
    <script src="scripts/prettify/lang-css.js"> </script>
    <!--[if lt IE 9]>
      <script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
    <![endif]-->
    <link type="text/css" rel="stylesheet" href="styles/prettify-tomorrow.css">
    <link type="text/css" rel="stylesheet" href="styles/jsdoc-default.css">
</head>

<body>

<div id="main">

    <h1 class="page-title">Module: datastore/query</h1>

    



<section>

<header>
    <h2>
    datastore/query
    </h2>
    
</header>

<article>
    <div class="container-overview">
    
        
<dt>
    <h4 class="name" id="module:datastore/query"><span class="type-signature"></span>new (require("datastore/query"))<span class="signature">(namespace<span class="signature-attributes">opt</span>, kinds)</span><span class="type-signature"></span></h4>

    
</dt>
<dd>

    
    <div class="description">
        <p>Build a Query object.</p>
<p><strong>Queries should be built with
<a href="dataset.html#createQuery"><code>module:datastore/dataset#createQuery</code></a> and run via
<a href="dataset.html#runQuery"><code>module:datastore/dataset#runQuery</code></a>.</strong></p>
<p><em>Reference: <a href="http://goo.gl/Cag0r6">http://goo.gl/Cag0r6</a></em></p>
    </div>
    

    

    

    
        <h5>Parameters:</h5>
        

<table class="params">
    <thead>
    <tr>
        
        <th>Name</th>
        

        <th>Type</th>

        
        <th>Attributes</th>
        

        

        <th class="last">Description</th>
    </tr>
    </thead>

    <tbody>
    

        <tr>
            
                <td class="name"><code>namespace</code></td>
            

            <td class="type">
            
                
<span class="param-type">string</span>


            
            </td>

            
                <td class="attributes">
                
                    &lt;optional><br>
                

                

                
                </td>
            

            

            <td class="description last"><p>Namespace to query entities from.</p></td>
        </tr>

    

        <tr>
            
                <td class="name"><code>kinds</code></td>
            

            <td class="type">
            
                
<span class="param-type">Array.&lt;string></span>


            
            </td>

            
                <td class="attributes">
                

                

                
                </td>
            

            

            <td class="description last"><p>Kinds to query.</p></td>
        </tr>

    
    </tbody>
</table>
    

    
<dl class="details">
    

    

    

    

    

    

    

    

    

    
    <dt class="tag-source">Source:</dt>
    <dd class="tag-source"><ul class="dummy"><li>
        <a href="query.js.html">datastore/query.js</a>, <a href="query.js.html#line53">line 53</a>
    </li></ul></dd>
    

    

    

    
</dl>


    

    

    

    

    

    

    
        <h5>Example</h5>
        
    <pre class="prettyprint"><code>var query;

// If your dataset was scoped to a namespace at initialization, your query
// will likewise be scoped to that namespace.
query = dataset.createQuery(['Lion', 'Chimp']);

// However, you may override the namespace per query.
query = dataset.createQuery('AnimalNamespace', ['Lion', 'Chimp']);

// You may also remove the namespace altogether.
query = dataset.createQuery(null, ['Lion', 'Chimp']);</code></pre>

    
</dd>

    

    
        

        
<dl class="details">
    

    

    

    

    

    

    

    

    

    
    <dt class="tag-source">Source:</dt>
    <dd class="tag-source"><ul class="dummy"><li>
        <a href="query.js.html">datastore/query.js</a>, <a href="query.js.html#line17">line 17</a>
    </li></ul></dd>
    

    

    

    
</dl>


        
    
    </div>

    

    

    

    

     

    

    

    
        <h3 class="subsection-title">Methods</h3>

        <dl>
            
<dt>
    <h4 class="name" id="end"><span class="type-signature"></span>end<span class="signature">(cursorToken)</span><span class="type-signature"> &rarr; {<a href="query.html">module:datastore/query</a>}</span></h4>

    
</dt>
<dd>

    
    <div class="description">
        <p>Set an ending cursor to a query.</p>
<p><em>Reference: <a href="http://goo.gl/WuTGRI">http://goo.gl/WuTGRI</a></em></p>
    </div>
    

    

    

    
        <h5>Parameters:</h5>
        

<table class="params">
    <thead>
    <tr>
        
        <th>Name</th>
        

        <th>Type</th>

        

        

        <th class="last">Description</th>
    </tr>
    </thead>

    <tbody>
    

        <tr>
            
                <td class="name"><code>cursorToken</code></td>
            

            <td class="type">
            
                
<span class="param-type">string</span>


            
            </td>

            

            

            <td class="description last"><p>The ending cursor token.</p></td>
        </tr>

    
    </tbody>
</table>
    

    
<dl class="details">
    

    

    

    

    

    

    

    

    

    
    <dt class="tag-source">Source:</dt>
    <dd class="tag-source"><ul class="dummy"><li>
        <a href="query.js.html">datastore/query.js</a>, <a href="query.js.html#line221">line 221</a>
    </li></ul></dd>
    

    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns:</h5>
    
            


<dl>
    <dt>
        Type
    </dt>
    <dd>
        
<span class="param-type"><a href="query.html">module:datastore/query</a></span>


    </dd>
</dl>

        

    
        <h5>Example</h5>
        
    <pre class="prettyprint"><code>var cursorToken = 'X';

// Retrieve results limited to the extent of cursorToken.
var endQuery = companyQuery.end(cursorToken);</code></pre>

    
</dd>

        
            
<dt>
    <h4 class="name" id="filter"><span class="type-signature"></span>filter<span class="signature">(filter, value)</span><span class="type-signature"> &rarr; {<a href="query.html">module:datastore/query</a>}</span></h4>

    
</dt>
<dd>

    
    <div class="description">
        <p>Datastore allows querying on properties. Supported comparison operators
are <code>=</code>, <code>&lt;</code>, <code>&gt;</code>, <code>&lt;=</code>, and <code>&gt;=</code>. &quot;Not equal&quot; and <code>IN</code> operators are
currently not supported.</p>
<p><em>To filter by ancestors, see <a href="query.html#hasAncestor"><code>module:datastore/query#hasAncestor</code></a>.</em></p>
<p><em>Reference: <a href="http://goo.gl/ENCx7e">http://goo.gl/ENCx7e</a></em></p>
    </div>
    

    

    

    
        <h5>Parameters:</h5>
        

<table class="params">
    <thead>
    <tr>
        
        <th>Name</th>
        

        <th>Type</th>

        

        

        <th class="last">Description</th>
    </tr>
    </thead>

    <tbody>
    

        <tr>
            
                <td class="name"><code>filter</code></td>
            

            <td class="type">
            
                
<span class="param-type">string</span>


            
            </td>

            

            

            <td class="description last"><p>Property + Operator (=, &lt;, &gt;, &lt;=, &gt;=).</p></td>
        </tr>

    

        <tr>
            
                <td class="name"><code>value</code></td>
            

            <td class="type">
            
                
<span class="param-type">*</span>


            
            </td>

            

            

            <td class="description last"><p>Value to compare property to.</p></td>
        </tr>

    
    </tbody>
</table>
    

    
<dl class="details">
    

    

    

    

    

    

    

    

    

    
    <dt class="tag-source">Source:</dt>
    <dd class="tag-source"><ul class="dummy"><li>
        <a href="query.js.html">datastore/query.js</a>, <a href="query.js.html#line97">line 97</a>
    </li></ul></dd>
    

    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns:</h5>
    
            


<dl>
    <dt>
        Type
    </dt>
    <dd>
        
<span class="param-type"><a href="query.html">module:datastore/query</a></span>


    </dd>
</dl>

        

    
        <h5>Example</h5>
        
    <pre class="prettyprint"><code>// List all companies named Google that have less than 400 employees.
var companyQuery = query
  .filter('name =', 'Google');
  .filter('size &lt;', 400);

// To filter by key, use `__key__` for the property name. Filter on keys
// stored as properties is not currently supported.
var keyQuery = query.filter('__key__ =', datastore.key('Company', 'Google'));</code></pre>

    
</dd>

        
            
<dt>
    <h4 class="name" id="groupBy"><span class="type-signature"></span>groupBy<span class="signature">(properties)</span><span class="type-signature"> &rarr; {<a href="query.html">module:datastore/query</a>}</span></h4>

    
</dt>
<dd>

    
    <div class="description">
        <p>Group query results by a list of properties.</p>
    </div>
    

    

    

    
        <h5>Parameters:</h5>
        

<table class="params">
    <thead>
    <tr>
        
        <th>Name</th>
        

        <th>Type</th>

        

        

        <th class="last">Description</th>
    </tr>
    </thead>

    <tbody>
    

        <tr>
            
                <td class="name"><code>properties</code></td>
            

            <td class="type">
            
                
<span class="param-type">array</span>


            
            </td>

            

            

            <td class="description last"><p>Properties to group by.</p></td>
        </tr>

    
    </tbody>
</table>
    

    
<dl class="details">
    

    

    

    

    

    

    

    

    

    
    <dt class="tag-source">Source:</dt>
    <dd class="tag-source"><ul class="dummy"><li>
        <a href="query.js.html">datastore/query.js</a>, <a href="query.js.html#line162">line 162</a>
    </li></ul></dd>
    

    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns:</h5>
    
            


<dl>
    <dt>
        Type
    </dt>
    <dd>
        
<span class="param-type"><a href="query.html">module:datastore/query</a></span>


    </dd>
</dl>

        

    
        <h5>Example</h5>
        
    <pre class="prettyprint"><code>var groupedQuery = companyQuery.groupBy(['name', 'size']);</code></pre>

    
</dd>

        
            
<dt>
    <h4 class="name" id="hasAncestor"><span class="type-signature"></span>hasAncestor<span class="signature">(key)</span><span class="type-signature"> &rarr; {<a href="query.html">module:datastore/query</a>}</span></h4>

    
</dt>
<dd>

    
    <div class="description">
        <p>Filter a query by ancestors.</p>
<p><em>Reference: <a href="http://goo.gl/1qfpkZ">http://goo.gl/1qfpkZ</a></em></p>
    </div>
    

    

    

    
        <h5>Parameters:</h5>
        

<table class="params">
    <thead>
    <tr>
        
        <th>Name</th>
        

        <th>Type</th>

        

        

        <th class="last">Description</th>
    </tr>
    </thead>

    <tbody>
    

        <tr>
            
                <td class="name"><code>key</code></td>
            

            <td class="type">
            
                
<span class="param-type">datastore/entity~Key</span>


            
            </td>

            

            

            <td class="description last"><p>Key object to filter by.</p></td>
        </tr>

    
    </tbody>
</table>
    

    
<dl class="details">
    

    

    

    

    

    

    

    

    

    
    <dt class="tag-source">Source:</dt>
    <dd class="tag-source"><ul class="dummy"><li>
        <a href="query.js.html">datastore/query.js</a>, <a href="query.js.html#line119">line 119</a>
    </li></ul></dd>
    

    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns:</h5>
    
            


<dl>
    <dt>
        Type
    </dt>
    <dd>
        
<span class="param-type"><a href="query.html">module:datastore/query</a></span>


    </dd>
</dl>

        

    
        <h5>Example</h5>
        
    <pre class="prettyprint"><code>var ancestoryQuery = query.hasAncestor(datastore.key('Parent', 123));</code></pre>

    
</dd>

        
            
<dt>
    <h4 class="name" id="limit"><span class="type-signature"></span>limit<span class="signature">(n)</span><span class="type-signature"> &rarr; {<a href="query.html">module:datastore/query</a>}</span></h4>

    
</dt>
<dd>

    
    <div class="description">
        <p>Set a limit on a query.</p>
<p><em>Reference: <a href="http://goo.gl/f0VZ0n">http://goo.gl/f0VZ0n</a></em></p>
    </div>
    

    

    

    
        <h5>Parameters:</h5>
        

<table class="params">
    <thead>
    <tr>
        
        <th>Name</th>
        

        <th>Type</th>

        

        

        <th class="last">Description</th>
    </tr>
    </thead>

    <tbody>
    

        <tr>
            
                <td class="name"><code>n</code></td>
            

            <td class="type">
            
                
<span class="param-type">number</span>


            
            </td>

            

            

            <td class="description last"><p>The number of results to limit the query to.</p></td>
        </tr>

    
    </tbody>
</table>
    

    
<dl class="details">
    

    

    

    

    

    

    

    

    

    
    <dt class="tag-source">Source:</dt>
    <dd class="tag-source"><ul class="dummy"><li>
        <a href="query.js.html">datastore/query.js</a>, <a href="query.js.html#line239">line 239</a>
    </li></ul></dd>
    

    

    

    
</dl>