Plywood

Plywood is a JavaScript library designed to simplify building interactive visualizations and applications for large datasets. It functions as a middle-layer between data visualizations (like D3.js) and data stores (like Apache Druid).

Key features include:

• Split-Apply-Combine Architecture: Uses a nested divide-and-conquer algorithm to construct various data visualizations.
• Expression Language: Features a custom expression language where a single expression can translate into multiple database queries.
• Nested Data Structures: Returns results in nested formats optimized for consumption by visualization libraries.
• Druid Query Planning: Acts as an advanced query planner for Druid, determining the most optimal execution paths for queries.

Plywood expressions are designed to be composed by method chaining. Most functions operate on an existing expression and return a new expression, allowing you to build complex logic step-by-step. For example, you can take a variable, perform arithmetic, and then apply a boolean predicate.

var ex = $('x').add(1).is(11);
ex.compute({ x: 10 }).then(console.log); // => true

Plywood supports NULL and BOOLEAN types:

• NULL: Represents the special type of null. It is a subtype of every other type.
• BOOLEAN: Represents true or false states, typically used for filtering.

// NULL
null

// BOOLEAN
true

Numeric data is handled via NUMBER and NUMBER_RANGE:

• NUMBER: Represents standard numeric attributes.
• NUMBER_RANGE: Represents an interval of numbers, commonly used for bucketing results.

// NUMBER
5

// NUMBER_RANGE
NumberRange.fromJS({ start: 4, end: 7.5 })

A DATASET is an abstract representation of a table (like in SQL) or a data source (like in Druid). It is a (potentially ordered) collection of datums, where each datum is a collection of attributes of the core types described in Plywood.

Dataset.fromJS([
  { x: 1, y: "USA" },
  { x: 2, y: "UK" }
])

Expressions are the fundamental building blocks of Plywood. The standard workflow involves constructing an expression (either via JSON or by composing operands) and then passing it to Plywood for evaluation using the .compute() method.

To evaluate an expression, you call ex.compute(context), where context is an object containing the values for any named references used within the expression.

var ex = $('x');
ex.compute({ x: 10 }).then(console.log); // => 10

Time-based attributes are represented by TIME and TIME_RANGE:

• TIME: Represents a specific point in time.
• TIME_RANGE: Represents an interval of time, often used for bucketing.

// TIME
new Date('2015-02-24T18:00:00Z')

// TIME_RANGE
TimeRange.fromJS({
  start: new Date('2015-02-24T18:00:00Z'), 
  end: new Date('2015-02-24T19:00:00Z') 
})

Categorical and collection data is handled via STRING and SET:

• STRING: Represents a categorical attribute.
• SET/X: Represents a set of distinct elements where all elements must share the same type X. For example, SET/NUMBER is a set of numbers.

// STRING
'USA'

// SET
Set.fromJS(['USA', 'UK', 'Japan'])

Plywood acts as a middle-layer between data visualizations and data stores. It is architected around the Split-Apply-Combine principle, allowing you to construct complex data visualizations through nested queries.

Key characteristics:

• Expression Language: A single Plywood expression can translate to multiple database queries.
• Nested Results: Results are returned in nested data structures, making them easy to consume by visualization libraries like D3.js.
• Query Planning: When used with Druid, Plywood acts as an advanced query planner to determine the most optimal execution path.