Added updated LiteStore user guide.
h3rald h3rald@h3rald.com
Sun, 25 Feb 2018 18:36:00 +0100
1 files changed,
178 insertions(+),
31 deletions(-)
M
assets/litestore/LiteStore_UserGuide.htm
→
assets/litestore/LiteStore_UserGuide.htm
@@ -2662,7 +2662,7 @@ text-shadow: 0 1px 0 rgba(255, 255, 255, 0.8);
color: #333; background-color: #f8f8f8; border: 1px solid #ccc; - white-space: pre; + white-space: pre-wrap; margin: auto; font-family: "Source Code Pro", "Monaco", "DejaVu Sans Mono", "Courier New", monospace; padding: 0;@@ -3262,9 +3262,9 @@ text-shadow: 0 1px 0 rgba(255, 255, 255, 0.8);
color: #eee; background-color: #222; border: 1px solid #ccc; - white-space: pre; padding: 0 3px; border: 2px solid #999; + white-space: pre-wrap; border-top: 10px solid #999; } .terminal a {@@ -3285,13 +3285,17 @@ }
} .terminal p, .terminal p:first-child { - margin-top: 0; + margin-top: -40px; margin-bottom: 0; text-shadow: none; font-weight: normal; font-family: "Source Code Pro", "Monaco", "DejaVu Sans Mono", "Courier New", monospace; font-size: 85%; color: #eee; +} +.terminal p:first-child, +.terminal p:first-child:first-child { + margin-top: 0px; } .terminal p:before, .terminal p:first-child:before {@@ -3315,9 +3319,9 @@ text-shadow: 0 1px 0 rgba(255, 255, 255, 0.8);
color: #eee; background-color: #222; border: 1px solid #ccc; - white-space: pre; padding: 0 3px; border: 2px solid #999; + white-space: pre-wrap; border-top: 10px solid #999; } .terminal-su a {@@ -3338,13 +3342,17 @@ }
} .terminal-su p, .terminal-su p:first-child { - margin-top: 0; + margin-top: -40px; margin-bottom: 0; text-shadow: none; font-weight: normal; font-family: "Source Code Pro", "Monaco", "DejaVu Sans Mono", "Courier New", monospace; font-size: 85%; color: #eee; +} +.terminal-su p:first-child, +.terminal-su p:first-child:first-child { + margin-top: 0px; } .terminal-su p:before, .terminal-su p:first-child:before {@@ -4365,6 +4373,7 @@ <li><a href="#Key-Features">Key Features</a>
<ul> <li><a href="#-Multi-format-Documents"> Multi-format Documents</a></li> <li><a href="#-Document-Tagging"> Document Tagging</a></li> + <li><a href="#-Enhanced-Querying-of-JSON-documents"> Enhanced Querying of JSON documents</a></li> <li><a href="#-Full-text-Search"> Full-text Search</a></li> <li><a href="#-RESTful-HTTP-API"> RESTful HTTP API</a></li> <li><a href="#-Directory-Bulk-Import/Export"> Directory Bulk Import/Export</a></li>@@ -4523,6 +4532,13 @@ </ul>
</li> <li><a href="#GET-docs">GET docs</a> <ul> + <li><a href="#<code>content</code>-option"><code>content</code> option</a></li> + <li><a href="#<code>limit</code>-and-<code>offset</code>-options"><code>limit</code> and <code>offset</code> options</a></li> + <li><a href="#<code>search</code>-option"><code>search</code> option</a></li> + <li><a href="#<code>tags</code>-option"><code>tags</code> option</a></li> + <li><a href="#<code>filter</code>-option"><code>filter</code> option</a></li> + <li><a href="#<code>select</code>-option"><code>select</code> option</a></li> + <li><a href="#<code>sort</code>-option"><code>sort</code> option</a></li> <li><a href="#Query-String-Options">Query String Options</a></li> <li><a href="#Example">Example</a></li> </ul>@@ -4545,7 +4561,8 @@ </ul>
</li> <li><a href="#PATCH-docs/:id">PATCH docs/:id</a> <ul> - <li><a href="#Example">Example</a></li> + <li><a href="#Example:-Patching-Tags">Example: Patching Tags</a></li> + <li><a href="#Example:-Patching-Daya">Example: Patching Daya</a></li> </ul> </li> <li><a href="#DELETE-docs/:id">DELETE docs/:id</a>@@ -4699,6 +4716,11 @@ <h4><span class="fa-tags"></span> Document Tagging<a href="#document-top" title="Go to top"></a></h4>
<p>You can add custom tags to documents to easily categorize them and retrieve them. Some system tags are also added automatically to identify the document content type, format and collection.</p> +<a name="-Enhanced-Querying-of-JSON-documents"></a> +<h4><span class="fa-tasks"></span> Enhanced Querying of JSON documents<a href="#document-top" title="Go to top"></a></h4> + +<p>By leveraging the <a href="https://www.sqlite.org/json1.html">SQLite JSON1 extension</a> and implementing custom query string parsing, LiteStore provides enhanced filtering, ordering, and custom field selection of JSON documents.</p> + <a name="-Full-text-Search"></a> <h4><span class="fa-search"></span> Full-text Search<a href="#document-top" title="Go to top"></a></h4>@@ -4853,12 +4875,12 @@
<p>The easiest way to get LiteStore is by downloading one of the prebuilt binaries from the [Github Release Page][release]:</p> <ul> -<li><a href="https://github.com/h3rald/litestore/releases/download/1.2.0litestore_1.2.0_macosx_x64.zip">LiteStore for Mac OS X (x64)</a> – Compiled on OS X El Capitan (LLVM CLANG 7.0.0)</li> -<li><a href="https://github.com/h3rald/litestore/releases/download/1.2.0/litestore_1.2.0_windows_x64.zip">LiteStore for Windows (x64)</a> – Cross-compiled on OS X El Capitan (MinGW-w64 GCC 4.8.2)</li> -<li><a href="https://github.com/h3rald/litestore/releases/download/1.2.0/litestore_1.2.0_windows_x86.zip">LiteStore for Windows (x86)</a> – Cross-compiled on OS X El Capitan (MinGW-w64 GCC 4.8.2)</li> -<li><a href="https://github.com/h3rald/litestore/releases/download/1.2.0/litestore_1.2.0_linux_x64.zip">LiteStore for Linux (x64)</a> – Cross-compiled on OS X El Capitan (GNU GCC 4.8.1)</li> -<li><a href="https://github.com/h3rald/litestore/releases/download/1.2.0/litestore_1.2.0_linux_x86.zip">LiteStore for Linux (x86)</a> – Cross-compiled on OS X El Capitan (GNU GCC 4.8.1)</li> -<li><a href="https://github.com/h3rald/litestore/releases/download/1.2.0/litestore_1.2.0_linux_arm.zip">LiteStore for Linux (ARM)</a> – Cross-compiled on OS X El Capitan (GNU GCC 4.8.2)</li> +<li><a href="https://github.com/h3rald/litestore/releases/download/1.3.0litestore_1.3.0_macosx_x64.zip">LiteStore for Mac OS X (x64)</a></li> +<li><a href="https://github.com/h3rald/litestore/releases/download/1.3.0/litestore_1.3.0_windows_x64.zip">LiteStore for Windows (x64)</a></li> +<li><a href="https://github.com/h3rald/litestore/releases/download/1.3.0/litestore_1.3.0_windows_x86.zip">LiteStore for Windows (x86)</a></li> +<li><a href="https://github.com/h3rald/litestore/releases/download/1.3.0/litestore_1.3.0_linux_x64.zip">LiteStore for Linux (x64)</a></li> +<li><a href="https://github.com/h3rald/litestore/releases/download/1.3.0/litestore_1.3.0_linux_x86.zip">LiteStore for Linux (x86)</a></li> +<li><a href="https://github.com/h3rald/litestore/releases/download/1.3.0/litestore_1.3.0_linux_arm.zip">LiteStore for Linux (ARM)</a></li> </ul>@@ -4889,7 +4911,7 @@
<p>To get the app up and running (assuming that you have the <span class="cmd">litestore</span> executable in your path):</p> <ol> -<li>Download the default <a href="https://github.com/h3rald/litestore/releases/download/1.2.0/data.db">data.db</a> file. This file is a LiteStore data store file containing the sample app.</li> +<li>Download the default <a href="https://github.com/h3rald/litestore/releases/download/1.3.0/data.db">data.db</a> file. This file is a LiteStore data store file containing the sample app.</li> <li>Go to the local directory in which you downloaded the <span class="cmd">data.db</span> file.</li> <li>Run <span class="cmd">litestore -s:data.db</span></li> <li>Go to <a href="http://localhost:9500/docs/admin/index.html">localhost:9500/docs/admin/index.html</a>.</li>@@ -5355,7 +5377,7 @@
<a name="HEAD-docs"></a> <h4>HEAD docs<a href="#document-top" title="Go to top"></a></h4> -<p>Retrieves all headers related to the docs resource and no content (this is probably not that useful, but at least it should make REST purists happy).</p> +<p>Retrieves all headers related to the <strong>docs</strong> resource and no content (this is probably not that useful, but at least it should make REST purists happy).</p> <a name="Example"></a> <h5>Example<a href="#document-top" title="Go to top"></a></h5>@@ -5406,27 +5428,112 @@
<a name="GET-docs"></a> <h4>GET docs<a href="#document-top" title="Go to top"></a></h4> -<p>Retrieves a list of documents in JSON format.</p> +<p>Retrieves a list of documents in JSON format. Several query string options are supported to query documents.</p> + +<a name="<code>content</code>-option"></a> +<h5><code>content</code> option<a href="#document-top" title="Go to top"></a></h5> + +<p>If set to <strong>false</strong>, do not retrieve document data.</p> + +<p>Example: http://127.0.0.1:9500/docs/?contents=false</p> -<a name="Query-String-Options"></a> -<h5>Query String Options<a href="#document-top" title="Go to top"></a></h5> +<a name="<code>limit</code>-and-<code>offset</code>-options"></a> +<h5><code>limit</code> and <code>offset</code> options<a href="#document-top" title="Go to top"></a></h5> -<p>The following query string options are supported:</p> +<p>Provide a way to implement pagination:</p> <ul> -<li><strong>search</strong> – Search for the specified string. Example: <code>http://127.0.0.1:9500/docs/?search=Something</code>.</li> -<li><strong>tags</strong> – Retrieve only documents with matching tag(s). Example: <code>http://127.0.0.1:9500/docs/?tags=tag1,tag2</code></li> -<li><strong>limit</strong> – Retrieve only the first <em>n</em> results. Example: <code>http://127.0.0.1:9500/docs/?limit=5</code></li> -<li><strong>offset</strong> – Skip the first <em>n</em> results. Example: <code>http://127.0.0.1:9500/docs/?offset=5</code></li> -<li><strong>sort</strong> – Sort by <strong>created</strong>, <strong>modified</strong>, and/or <strong>id</strong> (prepend <strong>-</strong> for DESC and <strong>+</strong> for ASC). Example: <code>http://127.0.0.1:9500/docs/?sort=-modified,-created</code></li> -<li><strong>contents</strong> – If set to <strong>false</strong>, do not retrieve document data. Example: <code>http://127.0.0.1:9500/docs/?contents=false</code></li> +<li><strong>limit</strong> causes the query to retrieve only the first <em>n</em> results.</li> +<li><strong>offset</strong> causes the query to skip the first <em>n</em> results.</li> </ul> +<p>Example: http://127.0.0.1:9500/docs/?limit=10&offset=20</p> + +<a name="<code>search</code>-option"></a> +<h5><code>search</code> option<a href="#document-top" title="Go to top"></a></h5> + +<p>Search for the specified string.</p> + +<p>Example: http://127.0.0.1:9500/docs/?search=Something</p> + <div class="tip"><p>Tip</p> <p>If <strong>search</strong> is specified, each result will contain a <strong>highlight</strong> property with a highlighted search snippet, and a <strong>rank</strong> property identified the rank of the result within the search. Results will also be automatically ordered by descending rank.</p></div> +<a name="<code>tags</code>-option"></a> +<h5><code>tags</code> option<a href="#document-top" title="Go to top"></a></h5> + +<p>Retrieve only documents with matching tag(s).</p> + +<p>Example: http://127.0.0.1:9500/docs/?tags=tag1,tag2</p> + +<a name="<code>filter</code>-option"></a> +<h5><code>filter</code> option<a href="#document-top" title="Go to top"></a></h5> + +<div class="note"><p>API v3 Required</p> + +<p>This query string option has been introduced in version 3 of the LiteStore API.</p></div> + +<p>Retrieve only JSON documents matching the specified filter expression.</p> + +<p>Filter expressions can be composed by one or more clauses joined together through <strong>or</strong> or <strong>and</strong> operators. Each clause must be composed exactly by:</p> + +<ul> +<li>A path expression indicating a field or array item within the JSON document.</li> +<li>One operator among the following: eq, not eq, gt, gte, lt, lte, contains.</li> +<li>A value that can be a number, string, <strong>true</strong>, <strong>false</strong> or <strong>nil</strong></li> +</ul> + + +<div class="warning"><p>Limitations</p> + +<ul> +<li>Parenthesis are not supported.</li> +<li>Up to 10 <strong>or</strong> clauses and 10 <strong>and</strong> clauses are supported.</li> +<li>Paths can only contain keys that contain only numbers, letters and underscores.</li> +</ul> +</div> + +<p>Examples:</p> + +<ul> +<li>http://127.0.0.1:9500/docs/?filter=$.age%20gte%2018%20or%20$.skills%20contains%20"maths"</li> +<li>http://127.0.0.1:9500/docs/?filter=$.name.first&20eq%20"Jack"%20or%20$.fav_food[0]%20eq%20"pizza"</li> +</ul> + + +<a name="<code>select</code>-option"></a> +<h5><code>select</code> option<a href="#document-top" title="Go to top"></a></h5> + +<div class="note"><p>API v3 Required</p> + +<p>This query string option has been introduced in version 3 of the LiteStore API.</p></div> + +<p>Retrieve JSON documents containing only the specified fields. Fields must be specified by comma-separated path/alias expression.</p> + +<p>Example: http://127.0.0.1:9500/docs/?select=$.name.first%20as%20FirstName,$.age%20as%20Age</p> + +<a name="<code>sort</code>-option"></a> +<h5><code>sort</code> option<a href="#document-top" title="Go to top"></a></h5> + +<p>Sort by <strong>created</strong>, <strong>modified</strong>, <strong>id</strong> or a JSON path to a field (prepend <strong>-</strong> for DESC and <strong>+</strong> for ASC).</p> + +<div class="note"><p>API v3 Required for JSON path support</p> + +<p>Support for JSON paths requires version 3 of the LiteStore API.</p></div> + +<p>Examples:</p> + +<ul> +<li>http://127.0.0.1:9500/docs/?sort=-modified,-created</li> +<li>http://127.0.0.1:9500/docs/?sort=-$.age,-$.name.first</li> +</ul> + + +<a name="Query-String-Options"></a> +<h5>Query String Options<a href="#document-top" title="Go to top"></a></h5> + <a name="Example"></a> <h5>Example<a href="#document-top" title="Go to top"></a></h5>@@ -5502,7 +5609,7 @@ <p>Retrieves a list of documents in JSON format starting with the specified folder path (it must end with ‘/’).</p>
<div class="tip"><p>Supported query options</p> -<p>The same query options of the <strong>docs</strong> resources are supported.</p></div> +<p>The same query options of the <strong>docs</strong> resource are supported.</p></div> <a name="Example"></a> <h5>Example<a href="#document-top" title="Go to top"></a></h5>@@ -5601,20 +5708,23 @@
<a name="PATCH-docs/:id"></a> <h4>PATCH docs/:id<a href="#document-top" title="Go to top"></a></h4> -<p>Adds, removes, replaces or tests the specified document for tags. Operations must be specified using the <a href="http://jsonpatch.com/">JSONPatch</a> format.</p> +<p>Adds, removes, replaces or tests the specified document for tags or data. Operations must be specified using the <a href="http://jsonpatch.com/">JSONPatch</a> format.</p> + +<div class="tip"><p>Tip</p> -<p>Always retrieve document tags first before applying a patch, to know the order tags have been added to the document.</p> +<p>If you plan on patching tags, always retrieve document tags first before applying a patch, to know the order tags have been added to the document.</p></div> <div class="warning"><p>Limitations</p> <ul> <li>Only <strong>add</strong>, <strong>remove</strong>, <strong>replace</strong> and <strong>test</strong> operations are supported.</li> -<li>It is currently only possible to change tags, not other parts of a document.</li> +<li>It is only possible to patch <strong>data</strong> and/or <strong>tags</strong> of a document.</li> +<li>It is only possible to patch the data of JSON documents.</li> </ul> </div> -<a name="Example"></a> -<h5>Example<a href="#document-top" title="Go to top"></a></h5> +<a name="Example:-Patching-Tags"></a> +<h5>Example: Patching Tags<a href="#document-top" title="Go to top"></a></h5> <pre><code>$ curl -i -X PATCH 'http://localhost:9500/docs/test.json' --header "Content-Type:application/json" -d '[{"op":"add", "path":"/tags/3", "value":"test1"},{"op":"add", "path":"/tags/4", "value":"test2"},{"op":"add", "path":"/tags/5", "value":"test3"}]' HTTP/1.1 200 OK@@ -5625,6 +5735,43 @@ Access-Control-Allow-Origin: *
Server: LiteStore/1.0.3 {"id": "test.json", "data": {"test": true}, "created": "2015-09-20T09:06:25Z", "modified": null, "tags": ["$type:application", "$subtype:json", "$format:text", "test1", "test2", "test3"]} +</code></pre> + +<a name="Example:-Patching-Daya"></a> +<h5>Example: Patching Daya<a href="#document-top" title="Go to top"></a></h5> + +<p>Given the following document:</p> + +<pre><code>{ + "id": "test", + "data": { + "name": { + "first": "Tom", + "last": "Paris" + }, + "rank": "lieutenant" + }, + "created": "2018-02-25T14:33:14Z", + "modified": null, + "tags": [ + "$type:application", + "$subtype:json", + "$format:text" + ] +} +</code></pre> + +<p>The following PATCH operation can be applied to change its data.</p> + +<pre><code>$ curl -i -X PATCH 'http://localhost:9500/docs/test' --header "Content-Type:application/json" -d '[{"op": "replace", "path": "/data/name", "value": "Seven of Nine"}, {"op": "remove", "path": "/data/rank"}]' +HTTP/1.1 200 OK +server: LiteStore/1.3.0 +access-control-allow-origin: * +content-type: application/json +access-control-allow-headers: Content-Type +Content-Length: 172 + +{"id":"test","data":{"name":"Seven of Nine"},"created":"2018-02-25T14:33:14Z","modified":"2018-02-25T14:35:52Z","tags":["$type:application","$subtype:json","$format:text"]} </code></pre> <a name="DELETE-docs/:id"></a>@@ -6067,7 +6214,7 @@ </ul>
</div> <div id="footer"> - <p><span class="copy"></span> Fabio Cevasco – October 29, 2017</p> + <p><span class="copy"></span> Fabio Cevasco – February 25, 2018</p> <p><span>Powered by</span> <a href="https://h3rald.com/hastyscribe"><span class="hastyscribe"></span></a></p> </div> </div>