Query Generation Parameterization

This section provides a complete reference for all query generation parameters. Beamline’s query generator is highly configurable, allowing you to control every aspect of query generation from simple predicates to complex nested path expressions.

Parameter Categories

Query generation parameters are organized into several categories:

1. Table Filter Parameters - Control WHERE clause generation
2. Projection Parameters - Control SELECT field selection
3. Exclusion Parameters - Control EXCLUDE clause generation
4. Path Parameters - Control how paths navigate data structures
5. Predicate Parameters - Control predicate types and operators
6. Type Parameters - Control what data types can be referenced

Table Filter Parameters

Control WHERE clause generation across all query strategies:

Filter Count

Example:

# Generate 1-3 predicates per WHERE clause
--tbl-flt-rand-min 1 --tbl-flt-rand-max 3

Filter Path Configuration

Example:

# Allow paths up to 3 levels deep
--tbl-flt-path-depth-max 3
# Results: field, object.field, object.nested.field

Table Filter Path Steps

Control what types of path steps can appear in WHERE clauses:

Internal Path Steps

Final Path Steps

Table Filter Type Constraints

Control what types of values can appear in WHERE clauses:

Projection Parameters

Control SELECT clause generation (applies to rand-sfw and rand-sefw strategies):

Projection Count

Example:

# Generate 2-5 fields in SELECT clause
--project-rand-min 2 --project-rand-max 5

Projection Path Configuration

Projection Path Steps

Same options as table filter path steps, but for SELECT clause:

Internal Path Steps

Final Path Steps

Projection Type Constraints

Exclusion Parameters

Control EXCLUDE clause generation (applies to rand-select-all-efw and rand-sefw strategies):

Exclusion Count

Exclusion Path Configuration

Exclusion Path Steps

Same structure as projection parameters:

Exclusion Type Constraints

Predicate Parameters

Control what types of predicates can be generated in WHERE clauses:

All Predicate Types

Null and Missing Predicates

Equality Predicates

Comparison Predicates

Numeric Predicates

String Predicates

Set Membership Predicates

Logical Predicates

Strategy Compatibility Matrix

Different parameters apply to different query strategies:

Configuration Examples

Simple Configuration

For basic testing with readable queries:

beamline query basic \
    --seed 100 \
    --start-auto \
    --script-path data.ion \
    --sample-count 10 \
    rand-select-all-fw \
        --tbl-flt-rand-min 1 \
        --tbl-flt-rand-max 2 \
        --tbl-flt-path-depth-max 2 \
        --tbl-flt-pathstep-internal-project \
        --tbl-flt-pathstep-final-project \
        --tbl-flt-type-final-scalar \
        --pred-comparison

Moderate Configuration

For comprehensive testing with controlled complexity:

beamline query basic \
    --seed 200 \
    --start-auto \
    --script-path data.ion \
    --sample-count 15 \
    rand-sfw \
        --project-rand-min 2 \
        --project-rand-max 4 \
        --project-path-depth-max 3 \
        --project-pathstep-internal-all \
        --project-pathstep-final-all \
        --project-type-final-all \
        --tbl-flt-rand-min 1 \
        --tbl-flt-rand-max 3 \
        --tbl-flt-path-depth-max 2 \
        --tbl-flt-pathstep-internal-all \
        --tbl-flt-pathstep-final-project \
        --tbl-flt-type-final-scalar \
        --pred-all

Complex Configuration

For edge case testing with maximum complexity:

beamline query basic \
    --seed 300 \
    --start-auto \
    --script-path nested_data.ion \
    --sample-count 20 \
    rand-sefw \
        --project-rand-min 3 \
        --project-rand-max 8 \
        --project-path-depth-min 2 \
        --project-path-depth-max 6 \
        --project-pathstep-internal-all \
        --project-pathstep-final-all \
        --project-type-final-all \
        --tbl-flt-rand-min 2 \
        --tbl-flt-rand-max 5 \
        --tbl-flt-path-depth-max 6 \
        --tbl-flt-pathstep-internal-all \
        --tbl-flt-pathstep-final-all \
        --tbl-flt-type-final-all \
        --exclude-rand-min 1 \
        --exclude-rand-max 4 \
        --exclude-path-depth-min 2 \
        --exclude-path-depth-max 4 \
        --exclude-pathstep-internal-all \
        --exclude-pathstep-final-all \
        --exclude-type-final-all \
        --pred-all

Parameter Combination Patterns

Testing Specific PartiQL Features

Test Wildcard Paths

# Focus on [*] and .* path expressions
beamline query basic \
    --seed 400 \
    --start-auto \
    --script-path array_data.ion \
    --sample-count 10 \
    rand-sfw \
        --project-rand-min 2 \
        --project-rand-max 4 \
        --project-pathstep-internal-foreach \
        --project-pathstep-internal-unpivot \
        --project-pathstep-final-foreach \
        --project-pathstep-final-unpivot \
        --pred-all

Test Deep Nesting

# Generate very deep path expressions
beamline query basic \
    --seed 500 \
    --start-auto \
    --script-path deeply_nested.ion \
    --sample-count 8 \
    rand-sfw \
        --project-path-depth-min 4 \
        --project-path-depth-max 8 \
        --tbl-flt-path-depth-min 3 \
        --tbl-flt-path-depth-max 6 \
        --exclude-path-depth-min 2 \
        --exclude-path-depth-max 5 \
        --pred-all

Test Null Handling

# Focus on null and missing value predicates
beamline query basic \
    --seed 600 \
    --start-auto \
    --script-path nullable_schema.ion \
    --sample-count 12 \
    rand-select-all-fw \
        --tbl-flt-rand-min 1 \
        --tbl-flt-rand-max 3 \
        --pred-absent --pred-logical-and --pred-logical-or

Performance Testing Configurations

Lightweight Queries

# Generate simple, fast-executing queries
beamline query basic \
    --seed 700 \
    --start-auto \
    --script-path performance_data.ion \
    --sample-count 25 \
    rand-select-all-fw \
        --tbl-flt-rand-min 1 \
        --tbl-flt-rand-max 1 \
        --tbl-flt-path-depth-max 1 \
        --tbl-flt-type-final-scalar \
        --pred-eq --pred-comparison

Heavy Queries

# Generate complex, resource-intensive queries
beamline query basic \
    --seed 800 \
    --start-auto \
    --script-path large_data.ion \
    --sample-count 15 \
    rand-sefw \
        --project-rand-min 8 \
        --project-rand-max 15 \
        --project-path-depth-max 6 \
        --tbl-flt-rand-min 5 \
        --tbl-flt-rand-max 10 \
        --tbl-flt-path-depth-max 5 \
        --exclude-rand-min 3 \
        --exclude-rand-max 8 \
        --pred-all

Common Parameter Patterns

Development and Debugging

# Simple, readable queries for development
--project-rand-min 1 --project-rand-max 3
--project-path-depth-max 2
--project-pathstep-final-project
--tbl-flt-rand-min 1 --tbl-flt-rand-max 2
--tbl-flt-path-depth-max 2
--pred-eq --pred-comparison

Integration Testing

# Moderate complexity for integration tests
--project-rand-min 2 --project-rand-max 5
--project-path-depth-max 3
--project-pathstep-internal-all --project-pathstep-final-all
--tbl-flt-rand-min 1 --tbl-flt-rand-max 4
--tbl-flt-path-depth-max 3
--exclude-rand-min 1 --exclude-rand-max 2
--pred-all

Stress Testing

# Maximum complexity for stress testing
--project-rand-min 5 --project-rand-max 12
--project-path-depth-min 3 --project-path-depth-max 8
--project-pathstep-internal-all --project-pathstep-final-all
--project-type-final-all
--tbl-flt-rand-min 3 --tbl-flt-rand-max 8
--tbl-flt-path-depth-max 6
--exclude-rand-min 2 --exclude-rand-max 6
--exclude-path-depth-min 2 --exclude-path-depth-max 5
--pred-all

Parameter Validation

Check Parameter Combinations

Some parameter combinations don’t make sense:

# Invalid - min > max
--tbl-flt-rand-min 5 --tbl-flt-rand-max 3  # Error

# Invalid - conflicting path steps  
--project-pathstep-final-project --project-pathstep-final-foreach  # May conflict

# Valid - consistent configuration
--tbl-flt-rand-min 1 --tbl-flt-rand-max 5
--project-rand-min 2 --project-rand-max 4

Default Behaviors

When parameters are not specified:

• Path depth: Unbounded (can generate very deep paths)
• Path steps: All types enabled by default
• Type constraints: All types allowed
• Predicate count: Implementation-dependent defaults

Recommendation: Always specify explicit bounds for predictable results.

Advanced Configuration Techniques

Targeted Testing

Test Specific Path Types

# Test only wildcard expressions
beamline query basic \
    --script-path array_data.ion \
    --sample-count 10 \
    rand-sfw \
        --project-pathstep-final-foreach \
        --project-pathstep-final-unpivot \
        --tbl-flt-pathstep-final-foreach \
        --pred-all

Test Specific Predicates

# Test only string operations
beamline query basic \
    --script-path text_data.ion \
    --sample-count 10 \
    rand-select-all-fw \
        --pred-like --pred-in --pred-eq

Graduated Complexity Testing

#!/bin/bash
# Generate test suites with graduated complexity

SCRIPT="test_schema.ion"
BASE_SEED=1000

# Level 1: Simple queries
beamline query basic \
    --seed $BASE_SEED \
    --start-auto \
    --script-path $SCRIPT \
    --sample-count 10 \
    rand-select-all-fw \
        --tbl-flt-rand-min 1 --tbl-flt-rand-max 1 \
        --pred-eq > level1.sql

# Level 2: Add comparisons  
beamline query basic \
    --seed $((BASE_SEED + 1)) \
    --start-auto \
    --script-path $SCRIPT \
    --sample-count 10 \
    rand-select-all-fw \
        --tbl-flt-rand-min 1 --tbl-flt-rand-max 2 \
        --pred-comparison > level2.sql

# Level 3: Add projections
beamline query basic \
    --seed $((BASE_SEED + 2)) \
    --start-auto \
    --script-path $SCRIPT \
    --sample-count 10 \
    rand-sfw \
        --project-rand-min 2 --project-rand-max 4 \
        --tbl-flt-rand-min 1 --tbl-flt-rand-max 2 \
        --pred-all > level3.sql

# Level 4: Add exclusions
beamline query basic \
    --seed $((BASE_SEED + 3)) \
    --start-auto \
    --script-path $SCRIPT \
    --sample-count 10 \
    rand-sefw \
        --project-rand-min 2 --project-rand-max 3 \
        --tbl-flt-rand-min 1 --tbl-flt-rand-max 3 \
        --exclude-rand-min 1 --exclude-rand-max 2 \
        --pred-all > level4.sql

echo "Generated graduated complexity test suite"

Performance Impact of Parameters

High Performance Impact

These parameters significantly affect query generation performance:

• High path depth (--path-depth-max 10+): Exponential complexity growth
• Many projections (--project-rand-max 20+): Large SELECT clauses
• Many predicates (--tbl-flt-rand-max 10+): Complex WHERE clauses
• All path steps enabled: More path generation options to evaluate

Low Performance Impact

These parameters have minimal impact:

• Predicate type selection: Doesn’t affect generation complexity
• Type constraints: Reduces rather than increases complexity
• Path step restrictions: Reduces generation options

Performance Optimization

# Optimized for speed
beamline query basic \
    --script-path data.ion \
    --sample-count 100 \
    rand-select-all-fw \
        --tbl-flt-rand-min 1 --tbl-flt-rand-max 3 \
        --tbl-flt-path-depth-max 2 \
        --tbl-flt-pathstep-final-project \
        --tbl-flt-type-final-scalar \
        --pred-comparison

# Comprehensive but slower
beamline query basic \
    --script-path data.ion \
    --sample-count 25 \
    rand-sefw \
        --project-rand-min 5 --project-rand-max 10 \
        --project-path-depth-max 5 \
        --tbl-flt-rand-min 3 --tbl-flt-rand-max 6 \
        --exclude-rand-min 2 --exclude-rand-max 4 \
        --pred-all

Troubleshooting Parameter Issues

Common Parameter Errors

Invalid Range Parameters

# Error: min > max
--tbl-flt-rand-min 5 --tbl-flt-rand-max 3

# Fix: min <= max
--tbl-flt-rand-min 3 --tbl-flt-rand-max 5

Conflicting Type Constraints

# May produce unexpected results
--project-type-final-scalar --project-pathstep-final-unpivot  # Scalar constraint conflicts with unpivot

# Better: consistent constraints
--project-type-final-all --project-pathstep-final-unpivot

Parameter Testing

# Test parameter combinations before large generation
beamline query basic \
    --seed 1 \
    --start-auto \
    --script-path test.ion \
    --sample-count 3 \
    rand-sefw \
        --project-rand-min 2 --project-rand-max 2 \
        --exclude-rand-min 1 --exclude-rand-max 1 \
        --pred-eq

# If results look good, scale up
# ... run with --sample-count 50

Best Practices

1. Start Conservative

# Begin with simple parameter values
--tbl-flt-rand-min 1 --tbl-flt-rand-max 2
--project-rand-min 1 --project-rand-max 3
--exclude-rand-min 1 --exclude-rand-max 1

2. Match Parameters to Data Structure

# Simple flat data
--project-path-depth-max 1 --tbl-flt-path-depth-max 1

# Nested object data  
--project-path-depth-max 3 --tbl-flt-path-depth-max 3

# Deeply nested data
--project-path-depth-max 6 --tbl-flt-path-depth-max 6

3. Use Consistent Parameter Ranges

# Good - balanced complexity
--project-rand-min 2 --project-rand-max 4
--tbl-flt-rand-min 1 --tbl-flt-rand-max 3
--exclude-rand-min 1 --exclude-rand-max 2

# Avoid - unbalanced (too many exclusions vs projections)
--project-rand-min 1 --project-rand-max 2
--exclude-rand-min 5 --exclude-rand-max 10

4. Document Your Configurations

# Create reusable parameter sets
SIMPLE_CONFIG="--tbl-flt-rand-min 1 --tbl-flt-rand-max 2 --pred-comparison"
MODERATE_CONFIG="--project-rand-min 2 --project-rand-max 4 --tbl-flt-rand-min 1 --tbl-flt-rand-max 3 --pred-all"

beamline query basic --script-path data.ion --sample-count 10 rand-select-all-fw $SIMPLE_CONFIG
beamline query basic --script-path data.ion --sample-count 10 rand-sfw $MODERATE_CONFIG

Reference Quick Guide

Most Common Configurations

Basic Testing:

rand-select-all-fw --tbl-flt-rand-min 1 --tbl-flt-rand-max 2 --pred-comparison

Projection Testing:

rand-sfw --project-rand-min 2 --project-rand-max 4 --tbl-flt-rand-min 1 --tbl-flt-rand-max 2 --pred-all

Exclusion Testing:

rand-select-all-efw --tbl-flt-rand-min 1 --tbl-flt-rand-max 2 --exclude-rand-min 1 --exclude-rand-max 3 --pred-all

Comprehensive Testing:

rand-sefw --project-rand-min 2 --project-rand-max 4 --exclude-rand-min 1 --exclude-rand-max 2 --tbl-flt-rand-min 1 --tbl-flt-rand-max 3 --pred-all

Next Steps

Now that you understand all parameterization options:

• CLI Query Commands - Complete CLI reference with parameter examples
• Basic Queries - Apply parameters to simple query generation
• Advanced Patterns - Use parameters for complex query patterns
• Examples - See parameterization in real-world scenarios