StarTree

Overview

StarTree is a relational database supporting SQL standards. It also supports JSON data storage and has several functions supporting JSON data interactions.

This tutorial covers the sample StarTree data. It can be loaded by the Qarbine administrator as described in the StarTree configuration document within the Administration documentation area. The concepts discussed apply quite broadly.

Defining a Data Source

Overview

A Data Source is a Qarbine component responsible for retrieving data from somewhere. At a high level it has a name, a description and some arbitrary query string which when sent to the associated Qarbine Data Service endpoint returns some data. The overall execution flow for an analysis, including the optional prompt component, is shown below.

  

A single data source can be referenced by name from multiple Qarbine template components. This enables a single point of change when perhaps, an index is added, or some other query tweak is necessary. The alternative is to attempt to find all templates impacted by a schema or index change for example. This component reusability is especially beneficial when team members have varying roles and skills.

This data source can be found at “example/StarTree/ecommerce/Top 5 ranked in Sports & Outdoors”.

The data source query specification below retrieves the top 5 products in the “Sports & Outdoors” department with some additional criteria.

select bought_past_month,brand,bs_category,bs_rank,department,description,features,
Image_url,ingredients,initial_price,final_price,is_available,item_weight,manufacturer,
number_of_sellers,prices_breakdown
product_dimensions,rating,reviews_count,root_bs_category,seller_name,
title,top_review,url
from product
where images != 'null'
and department = 'Sports & Outdoors'
and initial_price between 5 and 100
and bought_past_month >= 10
and image_url is not null
order by bs_rank asc
limit 5

Sample results are shown below.

  

The details of the first row are shown below

Managing Answer Set Size

NOTE- When querying a StarTree database using the REST API, the default number of rows returned is typically 10. This default behavior can be overridden by specifying a LIMIT clause in your query to adjust the number of rows returned.

The default maximum number of rows starts off at 25 for a new data source. This is useful to evolve a query from a concept to one that you have verified returns the desired answer set. As noted, any native way of limiting an answer set size is the preferred approach. This setting is in the component dialog as shown below and also accessible by clicking the ‘Gear’ icon.

  

Once you are done drafting you can adjust this parameter. A “0” indicates there is no maximum. A number greater than 0 indicates to limit the final answer set size to that number of rows. This answer set truncation comes after any native query limit. So, if the answer set from the data endpoint is quite large, that content has to be returned to the Qarbine host. It then may truncate the number of rows. It is best to truncate at the query level (i.e., use a limit) to reduce the content sent from the data endpoint to the Qarbine host in the first place.

Adjusting Maximum Rows

Recall the default maximum rows at the component level is 25. When you are satisfied with your query you can change that setting by clicking.

  

Adjust the setting to “0” indicating no Qarbine answer set truncation.

  

Click

  

Prompt Integration

Overview

Qarbine prompts provide a way to obtain runtime values and variables for data source and template execution. To avoid hardcoding, prompts can use macro formulas to run queries which populate list widgets. Prompts are defined in a no code manner using the Prompt Designer. Shown below is the execution flow when there is a Prompt component.

  

Sample Prompt

The Prompt Designer supports a large variety of input widgets including entry fields, check boxes, radio button groups, sliders, and file input. Shown below is a prompt for an initial price range.

  

Clicking

  

propagates the start and end initial price range values along to data sources and templates for their consumption.

This Prompt can be found at “Prompt`example/StarTree/ecommerce/Prompt for initial price range”. The prompt has the following elements.

  

The second prompt element has these main properties.

  

  

  

Since this slider is configured for adjusted start and end values, the resulting variables are rangeState and rangeEnd.

Adjusting the Data Source to Use the Prompt

The data source defined above uses a hard price range. Load that data source and follow the steps below to use a prompted range instead of a hard coded one.

The following new data source can be found at “example/StarTree/ecommerce/Top 5 ranked in Sports & Outdoors in price range”.
If you load the previously defined data source then immediately do a “Save as” action    to create a new data source. Give it a name such as “Top 5 ranked in Sports & Outdoors in price range”. You will use this data source in the following section describing template definition.

There are 2 main differences from the first data source:

1. The query spec has variables for the initial price range.

2. A prompt is referenced to obtain that range.

The adjusted query clause of interest is shown below.

and initial_price between @rangeStart and @rangeEnd

The overall adjusted query specification is shown below.

select bought_past_month,brand,bs_category,bs_rank,department,description,features,
image_url,ingredients,initial_price,final_price,is_available,item_weight,manufacturer,number_of_sellers,prices_breakdown
product_dimensions,rating,reviews_count,root_bs_category,seller_name,
title,top_review,url
from product
where images != 'null'
and department = 'Sports & Outdoors'
and initial_price between @rangeStart and @rangeEnd
and bought_past_month >= 10
and image_url is not null
order by bs_rank asc
limit 5

Associated the prompt by first clicking    to open the properties dialog.
Activate the Prompt tab.

  

Choose the drop down option shown below.

  

Since the prompt was just defined use the recents dialog button   to choose the prompt reference. The desired result is shown below.

  

Save the data source updates by clicking

  

Running the data source presents the prompt for you to adjust the range as shown below.

  

Click OK to have the range applied to the query.

  

Defining an Analysis Template

Overview

A template defines how to process the data being retrieved from Data Source queries and other data expressions. It also defines formulas, formatting options, and other analysis and presentation options. The overall execution flow for an analysis, including the optional prompt component, is shown below

  

Using the Template Designer

This template can be found at “example/StarTree/ecommerce/Top 5 ranked in Sports & Outdoors with range prompt”.

Sample output from the template is shown below.

  

Among the notable items are:

• Clicking on the   opens a web page on the product.

• The product image uses the custom image cell to render the product image from its URL. Clicking on it opens a zoom dialog on the image.

• The About, Features, and Review buttons are generated from the custom “Call out” cell. Click opens a dialog with the associated details.

• The “Is Available:” information uses the custom boolean cell.

• The price and revenue cells use currency formatting.

The overall template is shown below,

  

The ‘#’ prefix indicates a field of the current row. The ‘@’ prefix indicates a variable reference.

The first body line has these cells.

  

Review the template’s properties by clicking on   .
Notice it is associated with the data source defined above. Recall that data source is associated with the prompt described above as well.

  

  

The formatting options are shown below.

  

  

The page layout properties are shown below.

  

Running the template presents the prompt from the referenced data source for you to adjust the range. The start and end values flow into the query which is sent to Startree The answer set is then formatted based on the template specification.