DuckScript Guide

✨Why QuantQuack DSL (DuckScript)?

Your script automatically has access to these data columns. No setup needed!

📝Variables and Assignments

Create variables to store your calculations and make your code more readable:

range = high - low
ma = sma(close, 20)
signal = close > ma

# Calculate moving averages
ma20 = sma(close, 20)
ma50 = sma(close, 50)

# Detect golden cross
golden_cross = ma20 > ma50
above_ma20 = close > ma20

# Combine conditions
signal = golden_cross and above_ma20

output table

The DSL (DuckScript) supports different types of data. Most operations work automatically with series!

🔢Constants and Literals

Use literal values directly in your code - no need to declare them first!

# Using literals in your code
ma20 = sma(close, 20)           # 20 is an integer literal
threshold = 0.5                  # 0.5 is a float literal
is_enabled = true                # true is a boolean literal
session_name = "regular"         # "regular" is a string literal

# Using literals in expressions
breakout = high > high[1] * 1.005  # 1.005 is a float literal
output table

Reserved words and syntax details: input, func, signal, output, stats, summary, by, if/then/else, types. Don’t use them as variable names (except signal).

Special symbols used in the DSL (DuckScript) syntax:

⏮️Historical Values

Access values from previous periods using brackets []:

prev_close = close[1]    # Previous period's close
prev_high = high[1]      # Previous period's high
two_periods_ago = close[2]  # Two periods ago

# Compare current high to previous high
prev_high = high[1]
breakout = high > prev_high

output table

Powerful functions ready to use! Click any function name to see detailed documentation.

ma20 = sma(close, 20)

ema50 = ema(close, 50)

rsi14 = rsi(close, 14)

volatility = atr(14)

vwap_value = vwap()

abs_change = abs(close - open)

highest_20 = highest(high, 20)

lowest_20 = lowest(low, 20)

day_of_week = weekday(date)

# Use in aggregations
stats by session, weekday(date):
  count(breakout)
  percent(breakout)

consecutive_up = count_consecutive(up)

bars_since_breakout = bars_since(breakout)

golden_cross = crossover(ma_fast, ma_slow)

death_cross = crossunder(ma_fast, ma_slow)

ph = pivothigh(high, 2, 2)

pl = pivotlow(low, 2, 2)

highest_since_entry = high_since(signal)

lowest_since_entry = low_since(signal)

max_volume_since = max_since(breakout, volume)

min_volume_since = min_since(breakout, volume)

running_total = accumulate_while(volume > 1000, volume)

dq3_open = carry_while(session == "DQ3", open)

last_dq3_close = carry_forward(session == "DQ3", close)

entry_flag = flag_once(signal_entry)

lat = latch(signal, new_bar)

🔀Conditionals

Use if-expressions for conditional logic - choose values based on conditions:

# If-expression syntax
signal = if condition then value_if_true else value_if_false

# Example
is_bullish = close > open
signal_strength = if is_bullish then 1 else -1

# Multiple conditions
trend = if ma20 > ma50 then "up" else "down"

# Complex expressions
significant = if volume > 1000 then high else low

⚙️Input Parameters

Syntax detail: input at top of script.

Define configurable parameters at the top of your script - change them without modifying code!

input period = 20
input threshold = 0.5 as float
input use_sessions = true as bool

ma = sma(close, period)
breakout = high > high[1] * (1 + threshold)
output table

🔧User-Defined Functions

Define reusable functions inline - make your code more organized and maintainable:

# Define a function
func double(x: float) -> float = x * 2
func is_positive(x: float) -> bool = x > 0

# Use the function
doubled_close = double(close)
is_bullish = is_positive(close - open)

output table

📊Aggregations

Calculate statistics grouped by columns or expressions - powerful analysis made simple!

breakout = high > high[1] * 1.005

# Group by single column
stats by session:
  count(breakout) as total_breakouts
  percent(breakout) as breakout_probability
  avg(high - low) as avg_range

# Group by multiple columns
stats by session, interval_id:
  count(breakout)
  percent(breakout)

# Group by expressions (e.g., weekday)
stats by session, weekday(date):
  count(breakout_up) as breakout_up_count
  count(breakout_down)
  percent(breakout_up) as breakout_up_probability
  avg(2 * avg_volume) as double_avg_volume

# Optional: one row of aggregates over the stats by result
summary:
  count(breakout_up_count > 5) as high_breakout_sessions
  avg(breakout_up_probability) as avg_breakout_prob

output stats

📤Output

Specify what to output at the end of your script:

# Compare behavior at the same TIME position within each session
# interval_number = 1 means "first bar of each time interval" for all sessions
stats by session, interval_index, interval_number:
  count(close > open) as bullish_bars
  avg(high - low) as avg_range
  percent(volume > avg(volume, 20)) as high_volume

output stats

# Example: Compare first 30min behavior across all sessions

# Focus on first time interval within each session
# interval_number = 1 means first interval of each session
stats by session where interval_number = 1:
  count(high > high[1]) as breakouts
  avg(high - low) as avg_range
  max(high - low) as max_range

output stats

# Perfect for analyzing opening range behavior
# Note: interval_index is global, use interval_number for session-relative analysis

🚦Signals

Signals are boolean expressions that identify specific trading conditions. They're perfect for detecting entry/exit points, breakouts, and other trading opportunities.

# Declare signals explicitly
signal entry = crossover(sma(close, 12), sma(close, 26))
signal exit = crossunder(sma(close, 12), sma(close, 26))

# Signals with descriptive names
signal golden_cross = ma_fast > ma_slow and ma_fast[1] <= ma_slow[1]
signal price_breakout = high > high[1]

output signals

signal buy = close > sma(close, 20)
signal sell = close < sma(close, 20)
signal breakout = high > high[1]

signal = if close > ma20 then "buy"
         else if close < ma20 then "sell"
         else "hold"

signal = if close > ma20 then 1 else 0
signal_strength = if close > ma20 then 100 else 0

# These are automatically detected as signals
buy_signal = close > sma(close, 20)  # Contains "signal" in name
is_above_ma = close > ma              # Type is bool
breakout_detected = high > high[1]    # Type is bool

output signals

# Multiple signals
signal entry = crossover(ma_fast, ma_slow)
signal exit = crossunder(ma_fast, ma_slow)
breakout = high > high[1]  # Also detected as signal (type bool)

# Output only rows where at least one signal is true
output signals

above_ma = close > ma
high_volume = volume > 1000
breakout = high > high[1]

signal strong_entry = 
  above_ma and 
  high_volume and 
  breakout

signal strong_entry = 
  close > ma and 
  volume > 1000 and 
  high > high[1]

input ma_period = 20
input atr_period = 14
input volatility_threshold = 50

ma = sma(close, ma_period)
atr14 = atr(atr_period)

above_ma = close > ma
high_volatility = atr14 > volatility_threshold

signal strong_buy = above_ma and high_volatility
signal moderate_buy = above_ma and not high_volatility

output signals

# Golden Cross Strategy with Signals
input fast_period = 12
input slow_period = 26

ma_fast = sma(close, fast_period)
ma_slow = sma(close, slow_period)

# Explicit signals
signal entry = crossover(ma_fast, ma_slow)
signal exit = crossunder(ma_fast, ma_slow)

# Additional condition (auto-detected as signal)
above_ma = close > ma_fast

# Output only rows where signals are active
output signals

⚙️Config block & Backtesting

You can define backtest configuration (and optional script metadata) in two ways: in the script with a config block, or in the app using the graphical interface. The config block uses YAML syntax, starts with config: at the beginning of a line, and is optional—you can instead edit all backtest settings (signals, stop loss, take profit, capital, timeframes, etc.) in the app's UI.

Config block syntax

• Place config: at the start of a line (usually at the top of the file).
• Indent the following lines with spaces (YAML). The block ends when indentation returns to the base level.
• The block is stripped before compilation; only DuckScript code is compiled to SQL.

config:
  backtest:
    signals:
      entry:
        long: ["fast_breakout"]
        short: []
      exit:
        long: ["exit_signal"]
        short: []
    initialCapital: 10000
    positionSize: 1

# Your DuckScript below (signals must match names in config)
signal fast_breakout = high > high[1]
signal exit_signal = close < sma(close, 20)
output signals

Backtesting config (under config.backtest)

When you run a backtest, the engine uses the config block (or UI/defaults). Under backtest: you can set:

Signal names in the config must match signal names in your script. At least one entry signal (long or short) is required. If you omit the config block, backtest settings come from the app (graphical interface) or saved metadata.

💭DSL (DuckScript) Philosophy

❌What You Cannot Do

# ❌ This is NOT allowed
x = x[1] + 1

# ❌ This too
cnt = condition ? cnt[1] + 1 : 0

# ❌ Circular dependencies
a = b + 1
b = a + 1

up = close > close[1]
cnt = up ? nz(cnt[1]) + 1 : 0

up = close > close[1]
cnt = count_consecutive(up)

breakout = high > high[1]
bars_since = breakout ? 0 : bars_since[1] + 1

breakout = high > high[1]
bars_since = bars_since(breakout)

signal = crossover(ma_fast, ma_slow)
max_high = signal ? high : max(max_high[1], high)

signal = crossover(ma_fast, ma_slow)
max_high = high_since(signal)

sum = condition ? sum[1] + value : 0

sum = accumulate_while(condition, value)

❓FAQ

Quick answers to the most common DuckScript questions. For full reference, see Built-in Functions and What You Cannot Do.

📋Code Snippets

Copy-paste ready patterns. Scripts using session_end_timestamp or session_start_timestamp need a config: block with timezone and sessions.

is_session_end_bar = (session_end_timestamp(session) - timestamp) >= 0 and (session_end_timestamp(session) - timestamp) <= bar_size()

fast = sma(close, 10)
slow = sma(close, 20)
golden_cross = crossover(fast, slow)
death_cross = crossunder(fast, slow)

signal = close > sma(close, 20)
stats by session, date:
  count(signal) as signals
  percent(signal) as pct_up
  avg(close) as avg_close
output stats

config:
  timezone: "America/New_York"
  sessions:
    - name: "regular"
      start_time: "09:30"
      end_time: "16:00"
    - name: "premarket"
      start_time: "04:00"
      end_time: "09:30"

above_ma = close > sma(close, 20)
side = if above_ma then 1 else if close < sma(close, 20) then -1 else 0

consecutive_up = count_consecutive(close > open)
bars_since_breakout = bars_since(close > high[1])

prev_close = close[1]
gap_up = open > close[1]

rsi14 = rsi(close, 14)
atr14 = atr(14)
overbought = rsi14 > 70

fast_ma = sma(close, 10)
slow_ma = sma(close, 20)
signal long_entry = crossover(fast_ma, slow_ma)
signal short_entry = crossunder(fast_ma, slow_ma)
output signals

stats by date:
  count(*) as bars
  avg(close) as avg_close
  max(high) as day_high
output stats

stats by session, date:
  first(timestamp) as first_ts
  last(close) as last_close
  count(*) as bars
output stats

stats by date:
  max(high) as day_high
  min(low) as day_low

summary:
  count(day_high > day_low) as up_days
  avg(day_high) as avg_high

output stats

func double(x: float) -> float = x * 2
func above(a: float, b: float) -> bool = a > b

doubled_range = double(high - low)
is_above_ma = above(close, sma(close, 20))

valid_close = not na(close)
score = if valid_close then close - open else 0

config:
  timezone: "UTC"

range = high - low
output table