diff --git a/docs/tutorial-basics-query.markdown b/docs/tutorial-basics-query.markdown index f7bb1055..f44c8522 100644 --- a/docs/tutorial-basics-query.markdown +++ b/docs/tutorial-basics-query.markdown @@ -13,7 +13,7 @@ root: ../ ## Preparations -See first Dataset basics tutorial for getting setup and initializing Dataset. +See first Dataset basics tutorial for getting setup and initializing a Dataset. -Full details of the query structure and its options can be found in the reference documentation. +## Filtering -Also worth noting is that the last run query is stored as a Query instance in the `queryState` attribute of the Dataset object. Modifying `queryState` will also resulting in a query being run. This is useful when building views that want to display or manage the query state (see, for example, Query Editor or Filter Editor widgets). +A simple unstructured query like the one provided above searches all fieldsfor the value provided. +Often you want to "filter" results more precisely, for example by specifying a specific value in a specific field. To do this we use "filters". + +{% highlight javascript %} +var query = new recline.Model.Query(); +query.addFilter({type: 'term', field: 2}); +dataset.query(query); +{% endhighlight %} + +## QueryState + +The last run query is stored as a Query +instance in the `queryState` attribute of the Dataset object. Modifying +`queryState` will also resulting in a query being run. This is useful when +building views that want to display or manage the query state (see, for +example, Query Editor or Filter Editor widgets). + +## Full Details of the Query Language + +Full details of the query structure and its options +can be found in the reference documentation. diff --git a/docs/tutorial-basics.markdown b/docs/tutorial-basics.markdown index 9eef195d..a1e548d9 100644 --- a/docs/tutorial-basics.markdown +++ b/docs/tutorial-basics.markdown @@ -58,13 +58,11 @@ var dataset = new recline.Model.Dataset({ }); -## Records, Fields and more +## A Dataset and its Records Now that we have created a Dataset, we can use it. -For example, let's display some information about the Dataset and its records: - -
You can find out more about Dataset and Records in the reference documentation
+For example, let's display some information about the Dataset and its records using some of the key Dataset attributes: `recordCount` and `records`. {% highlight javascript %} {% include tutorial-basics-ex-1.js %} @@ -79,9 +77,42 @@ $('.ex-1').html(''); {% include tutorial-basics-ex-1.js %} -Note how the last geo attribute just rendered as `[object Object]`. This is because the Dataset is treating that field value as a string. Let's now take a look at the Dataset fields in more detail. +### Records -### Fields +`Dataset.records` is a Backbone Collection of `Record`s resutling from latest query. This need not (and usually isn't) **all** the records in this Dataset since the latest query need not have matched all records. + +
+Note that on initialization, a Dataset automatically queries for the first 100 records so this is what will usually be available in th records attribute. If you did want all records loaded into records at the start just requery after fetch has completed: + +{% highlight javascript %} +// for the async case need to put inside of done +dataset.fetch().done(function() { + dataset.query({size: dataset.recordCount}); +}); +{% endhighlight %} +
+ +As a Backbone Collection it supports all the standard Backbone collection functionality including methods like `each` and `filter`: + +{% highlight javascript %} +dataset.records.each(function(record) { + console.log(record.get('x') * 2); +}); + +var filtered = dataset.records.filter(function(record) { + return (record.get('z') > 4 && record.get('z') < 18); +}); + +// get all the values for a given attribute/field/column +var xvalues = dataset.records.pluck('x'); + +// calls toJSON on all records at once +dataset.records.toJSON(); +{% endhighlight %} + +
Want to know more about Dataset and Records? Check out the reference documentation
+ +## Fields In addition to Records, a Dataset has Fields stored in the `fields` attribute. Fields provide information about the fields/columns in the Dataset, for example their id (key name in record), label, type etc. @@ -100,7 +131,11 @@ $('.ex-fields').html(''); {% include tutorial-basics-ex-fields.js %} -As can be seen all fields have the default type of 'string'. Let's change the geo field to have type geo\_point and see what affect that has on displaying of the dataset (for good measure we'll also set the label): +As can be seen all fields have the default type of 'string'. + +As you may have noticed above the last geo attribute of the dataset just rendered as `[object Object]`. This is because the Dataset is treating that field value as a string. Let's now take a look at the Dataset fields in more detail. + +Let's change the geo field to have type geo\_point and see what affect that has on displaying of the dataset (for good measure we'll also set the label): {% highlight javascript %} {% include tutorial-basics-ex-fields-2.js %} @@ -113,5 +148,5 @@ $('.ex-fields-2').html(''); {% include tutorial-basics-ex-fields-2.js %} -As can be seen the rendering of the field has changed. This is because the `recordSummary` method uses the Record.getFieldValue function which in turn renders a record field using the Field's renderer function. This function varies depending on the type and can also be customized (see the Field documentation). +As can be seen the rendering of the field has changed. This is because the `summary` method uses the Record.getFieldValue function which in turn renders a record field using the Field's renderer function. This function varies depending on the type and can also be customized (see the Field documentation).