Excel Function Reference

BlazeXL exposes two core custom functions in Excel:

• PY for drafting, executing, and calling logic
• DATA for turning ranges into cloud-resident data handles or resolving shared objects

These functions are most useful when treated as part of a broader workflow:

• use Excel for authoring and interaction
• use BlazeXL for execution and governance
• use published Blaze Blocks for production logic

Recommended Usage Model

BlazeXL supports both exploratory work and governed execution inside Excel.

Exploratory Mode

Use PY and DATA when you want to:

• test a calculation
• prototype a transformation
• explore a model with spreadsheet inputs
• refine logic before publishing it

Governed Mode

Use published Blaze Blocks when the logic is meant to support production decisions.

That is the right model for:

• pricing and forecasting
• approval logic
• risk and policy checks
• finance and operations workflows

In governed mode, Excel stays the surface, while BlazeXL enforces versioning, permissions, execution controls, and auditability underneath.

PY() is used in both modes. The difference is what PY() is allowed to execute:

• in exploratory mode, PY() can draft and run ad hoc logic
• in strict mode, PY() can only call approved Block functions declared for the workbook

Understanding Handles

When you execute code or load data in BlazeXL, results are returned as Handles — lightweight references to high-performance objects living in the BlazeXL Cloud. This keeps Excel responsive even with large datasets.

Core Functions

=BLAZEXL.PY(code, [arg1], [arg2], ...)

The unified execution function.

PY can be used to:

• execute Python expressions
• define reusable functions
• call function handles
• call loaded or published Block functions
• work with handles returned from earlier formulas

For production workflows, use PY() to call reviewed Block functions rather than relying on ad hoc inline code.

• code: Python code, a function handle (\|F\|...\|), a lambda string, or a module function reference (e.g., math_utils.add).
• arg1...argN (Optional): Values from cells or handles. Available in Python as args['arg1'], args['arg2'], etc.

How a range argument arrives

A range passed straight to PY has no header row. To use the first row as column names, pass the range through DATA() first: =BLAZEXL.PY(code, BLAZEXL.DATA(A1:C50)).

Workbooks that used BlazeXL before this change keep their old behaviour: the first row of a block becomes the header. That is recorded in the workbook itself, so the file behaves the same on every machine. To move such a workbook to the new behaviour, run BlazeXL.rangeSemantics.set(2) from the add-in's developer console and recalculate.

Best used for

• drafting and validating logic in Excel
• turning a repeated formula pattern into a reusable function
• calling governed Block functions in production workbooks
• testing a Block function before standardizing a workbook around it

Examples:

Exploratory to governed example

# Explore logic in Excel
=BLAZEXL.PY("def discount(price, pct): return price * (1 - pct)")

# Validate behavior
=BLAZEXL.PY(A1, 100, 0.2)

# Publish the reviewed logic as a Blaze Block
# Then execute the approved version in governed workbooks
=BLAZEXL.PY("pricing.discount", 100, 0.2)

In strict mode, only the final form is allowed.

=BLAZEXL.DATA(data, [hasHeader], [dataType])

The unified data function. Creates DataFrames from ranges or resolves shared objects by name.

Use DATA when you want Excel ranges to participate in BlazeXL execution without moving large datasets directly into workbook formulas.

Mode 1: Range → DataFrame/Series

• data: An Excel range (e.g., A1:C50).
• hasHeader (Optional): Defaults to TRUE. Uses first row as column names.
• dataType (Optional): "dataframe" (default), "series", or "auto" (detects from shape).

Mode 2: Shared Object Resolution

When you pass a single cell containing a string, DATA resolves it from your organization's shared object registry:

=BLAZEXL.PY("df.groupby('region').sum()", BLAZEXL.DATA(A1:D50))

Shared Objects

Shared Objects let you publish data to your organization or team so that colleagues can reference it by name — without needing access to the original spreadsheet.

Publishing (via the Dashboard):

1. Click "Share" on any Table handle in the Dashboard workspace.
2. Give it a name (e.g., q4_sales) and choose visibility (team or org).

Consuming (in any Excel workbook):

=BLAZEXL.DATA("q4_sales")

This resolves the shared object through the governed access-control system, ensuring only authorized users in the correct team/org can access it.

Best Practices

1. Use PY in both modes, but change what it is allowed to execute. In exploratory workflows it can draft logic. In governed workflows it should invoke published Block functions only.

2. Pass DATA handles directly into PY for clean spreadsheet-to-runtime pipelines.

   =BLAZEXL.PY("df.describe()", BLAZEXL.DATA(A1:D50))
   

3. Use shared objects when teams need governed access to common datasets.

   =BLAZEXL.PY("forecast(sales)", BLAZEXL.DATA("company_sales"))
   

4. Call Block functions through PY when logic is approved and reused across systems.

   =BLAZEXL.PY("finance.npv", 0.08, BLAZEXL.DATA(B2:B20))
   

5. Use strict mode in governed workbooks. In strict mode, PY() cannot define arbitrary new logic and workbooks rely on declared, approved Block dependencies.

6. Let handles stay in the cloud. BlazeXL automatically manages large object lifecycles so Excel stays responsive while compute and storage remain off-grid.