Accessing all data in Hublify

Through the standardized dataset-api of the hublify-object you can access basically all the data stored in your Hublify.

Datasets are for example

• PIM Products & Categories & Supplemental Data, ...
• CRM Person, Groups, Leads, ...
• CMS Content, Assets, ...
• Databoxes, ...
• ... and even connected remote systems!
•  ... and many many more

Technically spoken these Hublify-functions integrate a very easy to use but yet powerful dataset-query-builder.

With that you can …

• Select (read) single records or a list of records,
• define what data-fields to select,
• filter for one or many field-values and/or predefined segments

Dataset Queries

You can fetch elements (records / entries, categories, assets, etc.) in your templates using dataset queries.

Working with dataset queries consists of three steps:

• (1) Create the dataset query. You do this by calling a “factory function” that is named after the element type you are going to fetch. For example, if you want to fetch entries, you’d call hublify.dataset('<your dataset>'), which returns a new entry query.
  
  
• (2) Set some parameters. By default, element queries will be configured to return all elements of the specified type. You can narrow that down to just the elements you care about by setting parameters on the query.
  
  
• (3) Execute the query. Once you’ve specified the query parameters, you’re ready for Hublify to fetch the elements and give you the results. You do that by calling .all() or .one(), depending on whether you need multiple elements, or just one.
  
  

Here’s what a typical dataset query might look like:

{# Create an entry query and set some parameters on it #}
{% set entryQuery = hublify.dataset('blog')
    .orderBy('postDate DESC')
    .limit(10) %}

{# Execute the query and get the results #}
{% set entries = entryQuery.all() %}

Each type of element has its own function for creating data queries, and they each have their own parameters you can set. See the individual element query pages for more details on working with them:

• Asset Queries
• Category Queries
• Menu Queries

dataset(...)

Creates a dataset-query-object.

Parameter: "<dataset>" A string containing the dataset-label.

Return: This functions returns dataset-query-object.

{# Creating a standalone query-object #}
{% set myQueryObj = hublify.dataset('blog') %}

Executing Dataset Queries

Once you’ve defined your parameters on the query, there are multiple functions available to execute it, depending on what you need back.

all() // will return <obj> soon

Most of the time, you just want to get the elements that you’re querying for. You do that with the all() function.

{% set entries = hublify.dataset('blog')
    .limit(10)
    .all() %}

allData()

Most of the time, you just want to get the elements that you’re querying for. You do that with the all() function.

{% set entries = hublify.dataset('blog')
    .limit(10)
    .allData() %}

allRich() // soon deprecated!

Most of the time, you just want to get the elements that you’re querying for. You do that with the all() function.

{% set entries = hublify.dataset('blog')
    .limit(10)
    .all() %}

one() // will return <obj> soon

If you only need a single element, call one() instead of all(). It will either return the element or null if no matching element exists.

{% set entry = hublify.dataset('person')
    .filter('firstname', 'Luke')
    .one() %}

oneData()

If you only need a single element, call one() instead of all(). It will either return the element or null if no matching element exists.

{% set entry = hublify.dataset('person')
    .filter('firstname', 'Luke')
    .oneData() %}

oneRich() // soon deprecated!

If you only need a single element, call one() instead of all(). It will either return the element or null if no matching element exists.

{% set entry = hublify.dataset('blog')
    .filter('firstname', 'Luke')
    .oneRich() %}

exists()  (...soon)

If you just need to check if any elements exist that match the element query, you can call exists(), which will return either true or false.

{% set exists = hublify.dataset('blog')
    .slug('hello-world')
    .exists() %}

count()  (...soon)

If you want to know how many elements match your element query, you can call count().

{% set count = hublify.dataset('blog')
    .count() %}

The limit and offset parameters will be ignored when you call count().

ids()  (...soon)

If you just want a list of matching element IDs, you can call ids().

{% set entryIds = hublify.dataset('blog')
    .ids() %}

Fields

Define the fields within the dataset record(s) you want to have returned.

For performance reasons it is useful to have ONLY THOSE FIELDS returned that YOU REALLY NEED!

field(...)

Adds one field to the dataset-query.

Parameter: Pass a string containing the field you want to add.

{# Adding the field "firstname" to the query #}
{% set myData = hublify.dataset('person').field('firstname').all() %}

{# Cascaded adding of single fields #}
{% set myData = hublify.dataset('person').field('firstname').field('lastname').field('gender').all() %}

fields(...)

Adds multiple fields you want to read to the dataset-query.

Parameter: Pass an array of strings of fields you want to add.

{# Adding three fields as an array to the query #}
{% set myData = hublify.dataset('person').fields(['firstname','lastname','gender']).all() %}

Filter

Once you’ve defined your parameters on the query, there are multiple functions available to execute it, depending on what you need back.

filter(...)

Adds a filter to your dataset-query. A filter is in fact like a partial WHERE-statement within an SQL-query.

The generic syntax is:

function filter(string $field, $value = null, string $operator = null)

A simple example

{# Getting all persons "firstname" whos "lastname" is "skywalker" #}
{% set myData = hublify.dataset('person').field('firstname').filter('lastname','skywalker').all() %}

But actually the filter function supports some very nice extra options for different filter-modes.
You can engage those by setting the operator-parameter.

"equal" (default) - exact match

This is the default mode.

"search" - "smart Filter"

A very powerful search mode applicable to text, number, date and datetime fields.

"in" - OR-based multiple values

The value-parameter be then an array of strings.

Set the operator-parameter to "in".

An example

{# Getting all products with brand is "nike" OR "reebok" OR "adidas" #}
{% set myData = hublify.dataset('product').field('pcode').filter('brand', ["nike","reebok","adidas"], 'in').all() %}

"not_in" - AND-based exclusion of values

The value-parameter be then an array of strings.

Set the operator-parameter to "not_in".

An example

{# Getting all products that are neither of the brands: "nike" AND "reebok" AND "adidas" #}
{% set myData = hublify.dataset('product').field('pcode').filter('brand', ["nike","reebok","adidas"], 'not_in').all() %}

"range" - min/max based for numbers

To filter in numerical fields with greater-than and/or less-then values you can this range-operator.

The value-parameter be then an object containing one or two of these members (keys):

• 'min' - number. Describing the range's lower end.
• 'max' - number. Describing the range's upper end.

Set the operator-parameter to "range".

An example

{# Getting all products with a price >= 30 and < 100 #}
{% set myData = hublify.dataset('product').field('pcode').filter('price', { 'min': 30, 'max': 100 }, 'range').all() %}

filters(...)

Adds multiple filters to your dataset-query at once.

{# Getting all persons "firstname" filtered for the "firstname" and "lastname" #}
{% set myData = hublify.dataset('person').field('firstname').filters( {'lastname':'skywalker', 'firstname':'luke'} ).all() %}

segment(...)

Adds a filtering segment to your dataset-query.

{# Adding the segment "bday_next_within_7days" to the query #}
{% set myData = hublify.dataset('person').segment('bday_next_within_7days').all() %} 

Of course you can combine segments with other filters!

segments(...)

Adds multiple segments for filtering to your dataset-query at once.

{# Adding multiple segments to the query #}
{% set myData = hublify.dataset('person').segments(['bday_next_within_7days','a-customer']).all() %}  

Control

A good data retrieval is nothing without sorting and limits...

orderBy(...)

Adds an ordering to your retrieved data.

{# Enabling a ordering by field "name" in ascending order #}
{% set myData = hublify.dataset('product').fields(['pcode','name']).orderBy('name', 'ASC').all() %}

Parameter: First parameter is the field name, the second the order-direction ("ASC|DESC").

{# Limit the number to the first 5 products #}
{% set myData = hublify.dataset('product').fields(['pcode','name']).limit(5).all() %}

{# Get products from position 100 .. 104 #}
{% set myData = hublify.dataset('product').fields(['pcode','name']).limit(5).offset(100).all() %}

{# Return the total number of rows as well - even if limit the returned rows to 5 #}
{% set myData = hublify.dataset('product').fields(['pcode','name']).limit(5).countTotal().all() %}

groupBy(string $field, ?string $cluster = null)

measure(string $field, string $aggregation, string $alias = null)

principal(string $field, ?string|array $cluster = null, bool $padding = false)

{% set myData = hublify.dataset('person').param('anExampleVar','itsValue').field('firstname').filter('lastname','skywalker').all() %}

{% set myData = hublify.dataset('person').params([ {'exVar1':'Value1'}, {'exVar2':'Value2'}]).field('firstname').filters([ {'lastname':'skywalker'}, {'firstname':'luke'}]).all() %}