terraformer

<!doctype html> <html> <head> <meta charset="utf-8"> <meta content="IE=edge,chrome=1" http-equiv="X-UA-Compatible"> <title>Terraformer</title> <link href="/assets/css/terraformer-02847305.css" media="screen" rel="stylesheet" type="text/css" /> </head> <body class="geostore geostore_index" id="wrap"> <nav> <ul> <li> <a href="/" class="">Terraformer</a> </li> <li> <a href="https://github.com/search?q=%40Esri+terraformer" class="">GitHub</a> </li> <li> <a href="/install" class="">Install</a> </li> <li> <a href="/" data-direction="active-top" class="toggle" id="close-drawer">Docs</a> </li> </ul> </nav> <div class="drawer" id="drawer"> <div class="doctoc drawer-nav drawer-top"> <div class="container"> <ul> <h3>Terraformer Documentation</h3> <li><a href="/getting-started/">Getting Started</a></li> <li><a href="/core/">Terraformer Core</a></li> <li class="indent"><a href="/core/#terraformerprimitive">Primitives</a></li> <li class="indent"><a href="/core/#terraformertools">Tools</a></li> <li><a href="/geostore/">GeoStores</a></li> <li class="indent"><a href="/geostore/data-stores/">DataStores</a></li> <li class="indent"><a href="/geostore/spatial-indexes/">Spatial Indexes</a></li> <li><a href="/arcgis-parser/">ArcGIS Parser</a></li> <li><a href="/wkt-parser/">WKT Parser</a></li> <li><a href="/glossary/">Glossary</a></li> </ul> </div> </div> </div> <main class="docs main-content" id="main-content"> <h1>GeoStore</h1> <div class='semantic-toc'><ol><li><a href='#using-the-geostore'>Using the GeoStore</a><ol><li><a href='#using-in-the-browser'>Using in the Browser</a></li><li><a href='#using-in-nodejs'>Using in Node.js</a></li><li><a href='#methods'>Methods</a><ol><li><a href='#geostoreadd'>GeoStore.add(geojson, callback)</a></li><li><a href='#geostoreupdate'>GeoStore.update(geojson, callback)</a></li><li><a href='#geostoreremove'>GeoStore.remove(id, callback)</a></li><li><a href='#geostoreget'>GeoStore.get(id, callback)</a></li><li><a href='#geostorecontains'>GeoStore.contains(geojson, search, callback)</a></li><li><a href='#geostorewithin'>GeoStore.within(geojson, search, callback)</a></li><li><a href='#geostorecreatereadstream'>GeoStore.createReadStream()</a></div> The Terraformer GeoStore is a set of building blocks for managing spatial data as a GeoJSON <code>Feature</code> or <code>FeatureCollection</code>. It includes functionality for storing and querying data in primarily a spatial manner. GeoStores are broken into three parts: <a href="/geostore/data-stores">Data Stores</a>, <a href="/geostore/spatial-indexes">Spatial Indexes</a>, and <a href="/geostore/alternate-indexes">Alternate Indexes</a>. More in-depth information can be found in <a href="/geostore/core-concepts">Core Concepts</a>. <h2> <a id='using-the-geostore' class='section-link'></a> <a href='#using-the-geostore' class='header-link'>Link</a> Using the GeoStore <a href='#' class='back-to-top-link'>Back to Top</a> </h2> The GeoStore can be used in both the browser and server-side via Node.js. Functionally, they behave the same, but some Data Stores and Indexes will only work in one environment. For instance, LocalStorage will not work by default in Node.js. The GeoStore uses Node.js style callbacks, so most method signatures require a <code>callback</code> function that expects <code>error</code> and <code>response</code>: <code>function (err, res) { }</code>. The GeoStore manages data that is made available as either a <code>Feature</code> or a <code>FeatureCollection</code>. In order to work, there must be an <code>id</code> field. <pre class="highlight javascript"><code>{ "type": "Feature", "properties": {}, "id": "my id", "geometry": { "type": "Polygon", "coordinates": [ [ [ -111.09374, 41.50857 ], [ -111.09374, 45.08903 ], [ -105.11718, 45.08903 ], [ -105.11718, 41.50857 ], [ -111.09374, 41.50857 ] ] ] } } </code></pre> <h3> <a id='using-in-the-browser' class='section-link'></a> <a href='#using-in-the-browser' class='header-link'>Link</a> Using in the Browser <a href='#' class='back-to-top-link'>Back to Top</a> </h3> Using the GeoStore in the browser requires including both Terraformer and the GeoStore: <pre class="highlight html"><code><script src="terraformer.min.js"></script> <script src="terraformer-geostore.min.js"></script> </code></pre> Once those are included, you can create a new <code>Store</code>. You will need to include both a Data Store and a Spatial Index to instantiate a GeoStore. <pre class="highlight javascript"><code>// create a new GeoStore using Memory and an RTree Index var store = new Terraformer.GeoStore({ store: new Terraformer.Store.Memory(), index: new Terraformer.RTree() }); </code></pre> Once the store has been created, you can start using it right away. <h3> <a id='using-in-nodejs' class='section-link'></a> <a href='#using-in-nodejs' class='header-link'>Link</a> Using in Node.js <a href='#' class='back-to-top-link'>Back to Top</a> </h3> In Node.js, the components are available via <code>require()</code>. <pre class="highlight javascript"><code>// require geostore, an RTree index, and a LevelDB data store var GeoStore = require('terraformer-geostore').GeoStore; var RTree = require('terraformer-rtree').RTree; var LevelStore = require('terraformer-geostore-leveldb'); </code></pre> Once the packages are in scope, it is very similar as using the GeoStore in the browser. <pre class="highlight javascript"><code>var store = new GeoStore({ store: new LevelStore(), index: new RTree() }); </code></pre> <h3> <a id='methods' class='section-link'></a> <a href='#methods' class='header-link'>Link</a> Methods <a href='#' class='back-to-top-link'>Back to Top</a> </h3><h4> <a id='geostoreadd' class='section-link'></a> <a href='#geostoreadd' class='header-link'>Link</a> GeoStore.add(geojson, callback) <a href='#' class='back-to-top-link'>Back to Top</a> </h4> Add a <code>geojson</code> object to the GeoStore. <table><thead> <tr> <th>Option</th> <th>Value</th> <th>Description</th> </tr> </thead><tbody> <tr> <td><a href="/glossary/#geojson"><code>GeoJSON</code></a></td> <td><code>object</code></td> <td>Must be either a <code>Feature</code> or <code>FeatureCollection</code> and contain an <code>id</code></td> </tr> <tr> <td>callback</td> <td><code>function</code></td> <td>Callback to be fired when the <code>add</code> has been completed</td> </tr> </tbody></table> Example: <pre class="highlight javascript"><code>store.add(geojson, function (err, res) { // Node.js style callback }); </code></pre> <h4> <a id='geostoreupdate' class='section-link'></a> <a href='#geostoreupdate' class='header-link'>Link</a> GeoStore.update(geojson, callback) <a href='#' class='back-to-top-link'>Back to Top</a> </h4> Update a single <code>geojson</code> <code>Feature</code> in the GeoStore. <table><thead> <tr> <th>Option</th> <th>Value</th> <th>Description</th> </tr> </thead><tbody> <tr> <td><a href="/glossary/#geojson"><code>GeoJSON</code></a></td> <td><code>object</code></td> <td>Must be a <code>Feature</code> and contain an <code>id</code></td> </tr> <tr> <td>callback</td> <td><code>function</code></td> <td>Callback to be fired when the <code>update</code> has been completed</td> </tr> </tbody></table> Example: <pre class="highlight javascript"><code>store.update(geojson, function (err, res) { // Node.js style callback }); </code></pre> <h4> <a id='geostoreremove' class='section-link'></a> <a href='#geostoreremove' class='header-link'>Link</a> GeoStore.remove(id, callback) <a href='#' class='back-to-top-link'>Back to Top</a> </h4> Removes a single <code>geojson</code> <code>Feature</code> by <code>id</code>. <table><thead> <tr> <th>Option</th> <th>Value</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>id</td> <td><code>String</code> or <code>Number</code></td> <td>The <code>id</code> of the <code>Feature</code> to be removed</td> </tr> <tr> <td>callback</td> <td><code>function</code></td> <td>Callback to be fired when the <code>remove</code> has been completed</td> </tr> </tbody></table> Example: <pre class="highlight javascript"><code>store.remove(id, function (err, res) { // Node.js style callback }); </code></pre> <h4> <a id='geostoreget' class='section-link'></a> <a href='#geostoreget' class='header-link'>Link</a> GeoStore.get(id, callback) <a href='#' class='back-to-top-link'>Back to Top</a> </h4> Retrieves a single <code>geojson</code> <code>Feature</code> by <code>id</code>. <table><thead> <tr> <th>Option</th> <th>Value</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>id</td> <td><code>String</code> or <code>Number</code></td> <td>The <code>id</code> of the <code>Feature</code> to be retrieved</td> </tr> <tr> <td>callback</td> <td><code>function</code></td> <td>Callback to be fired when the <code>get</code> has been completed</td> </tr> </tbody></table> Example: <pre class="highlight javascript"><code>store.get(id, function (err, res) { // Node.js style callback }); </code></pre> <h4> <a id='geostorecontains' class='section-link'></a> <a href='#geostorecontains' class='header-link'>Link</a> GeoStore.contains(geojson, search, callback) <a href='#' class='back-to-top-link'>Back to Top</a> </h4> Find all <code>Features</code> that contain the <code>geojson primitive</code> passed in. <code>contains</code> can use additional indexes to do set elimination on properties of a <code>Feature</code>. <table><thead> <tr> <th>Option</th> <th>Value</th> <th>Description</th> </tr> </thead><tbody> <tr> <td><a href="/glossary/#geojson"><code>GeoJSON</code></a></td> <td><code>object</code></td> <td>A GeoJSON primitive to search with</td> </tr> <tr> <td>search (optional)</td> <td><code>object</code></td> <td>The second argument is optional. If provided it contains additional search criteria for set elimination</td> </tr> <tr> <td>callback</td> <td><code>function</code></td> <td>Callback to be fired when the <code>contains</code> has been completed</td> </tr> </tbody></table> Example: <pre class="highlight javascript"><code>store.contains(geojson, function (err, res) { // Node.js style callback }); store.contains( geojson, { "name": { "equals": "Multnomah" } }, function (err, res) { // Node.js style callback } ); </code></pre> <h4> <a id='geostorewithin' class='section-link'></a> <a href='#geostorewithin' class='header-link'>Link</a> GeoStore.within(geojson, search, callback) <a href='#' class='back-to-top-link'>Back to Top</a> </h4> Find all <code>Features</code> that are within the <code>geojson primitive</code> passed in. <code>within</code> can use additional indexes to do set elimination on properties of a <code>Feature</code>. <table><thead> <tr> <th>Option</th> <th>Value</th> <th>Description</th> </tr> </thead><tbody> <tr> <td><a href="/glossary/#geojson"><code>GeoJSON</code></a></td> <td><code>object</code></td> <td>A GeoJSON primitive to search with</td> </tr> <tr> <td>search (optional)</td> <td><code>object</code></td> <td>The second argument is optional. If provided it contains additional search criteria for set elimination</td> </tr> <tr> <td>callback</td> <td><code>function</code></td> <td>Callback to be fired when the <code>within</code> has been completed</td> </tr> </tbody></table> Example: <pre class="highlight javascript"><code>store.within(geojson, function (err, res) { // Node.js style callback }); store.within( geojson, { "name": { "equals": "Multnomah" } }, function (err, res) { // Node.js style callback } ); </code></pre> <h4> <a id='geostorecreatereadstream' class='section-link'></a> <a href='#geostorecreatereadstream' class='header-link'>Link</a> GeoStore.createReadStream() <a href='#' class='back-to-top-link'>Back to Top</a> </h4> GeoStore supports readable streams in both the browser and Nodejs. Currently only <code>flowing</code> streams are supported. Streams can be created with the <code>createReadStream()</code> method. When a stream has been created, the next <code>within</code> or <code>contains</code> request uses that stream in place of a callback. It is important to note that the stream only lasts for the duration of a single search via <code>within</code> or <code>contains</code>. The stream will emit <code>data</code> on any data, and <code>end</code> with the final entry found. Since streams are not reentrant in the GeoStore, it is recommended to create a new GeoStore for each stream. Streams are destroyed after the <code>end</code> event has been called. Example: <pre class="highlight javascript"><code>var stream = store.createReadStream(); stream.on("data", function (geojson) { // found geojson }); stream.on("end", function (geojson) { // final geojson object }); </code></pre> </main> <footer> Terraformer is an open source project from the <a href="http://pdx.esri.com/">Esri Portland R&D Center</a> </footer> <script src="/assets/javascripts/modernizr.custom-cadc78a2.js" type="text/javascript"></script> <script src="/assets/javascripts/classie-b6db1f70.js" type="text/javascript"></script> <script src="/assets/javascripts/drawer-3a1490eb.js" type="text/javascript"></script> </body> </html>