Technical Documentation

Many of the features in ClearFactr were built specifically to eliminate the struggle you’d probably encounter trying to do the same thing with a traditional spreadsheet. This quick overview is designed to make you aware of some key capabilities so you can leverage them when you build your models, and collaborate around them with others.

We’d encourage you to review our “ClearFactr Solution Design Patterns” materials, which also includes specific Case Studies on how these Design Patterns have been successfully leveraged in the past. 

Continue Reading...

Initial Setup

When you first get your ClearFactr account, AWS will send you an email with your username and a temporary password. You'll need to log into the system within 7 days of receiving that, at which point you can choose your own password.

Changing your Password

If you want or need to change your password, simply go to the Login panel and look for the "Forgot your password?" link, just below the Password field. Click that and follow the instructions as provided by AWS.

Note:

1. You'll need access to the associated email address; AWS will send you a temporary security code there which you'll use during the reset process.
2. You may notice in the AWS panel that what appears to be an email address may look wrong. This is an intentional "security through obfuscation" mechanism employed by AWS.

Cell Types:

• Root Cells: These cells contain data, either hand-typed or set via external API calls, that are used by Formula Cells and represent the starting points of all calculation chains.
• Formula Cells: As noted above, a formula cell computes a value using one or more Root Cells, or the values of other formula cells, as inputs.
• Terminal Cells: A terminal cell is also a formula cell, but its value does not drive anything else in the model. Thus, a given calculation chain "terminates" with this type of cell. 
• Cell Ancestry: This refers to the computational lineage of a given cell, in the context of one or more compute chains. Values that a given cell relies up to compute its own value are called "parents", and cells whose values are controlled by a given cell are considered "children".

All of ClearFactr's Natural Language renderings are driven by the row headers and column headers that you can optionally supply. If present, ClearFactr's Natural Language toggle will use those headers to re-render your formulas, transforming something like "A3" into "Gross Profit @ Q4 2025"

Note that the naming scheme applies the row header first, then the column header. So for example, if row 3 is named "Western Region" and column D is called "Projection", D3 would be described as "Western Region's Projection". This is loosely analogous to properties in a database table's structure, where every row might have a value for every given property.

You can type this row and column headers by hand, but you can also use the grid's context menu feature to "push" text values from cells to either the row or column headers.

[picture]

Navigation

^{Move quickly between cells and tabs.}

Selection

^{Select ranges, rows, and columns efficiently.}

Other

How to Open It

1. Select the cells you want to move.
2. Right-click to open the context menu.
3. Click Move Range....

The dialog opens with a summary of your selection at the top, showing the tab name, the cell range, and the dimensions (e.g., "Summary A1:D10 (4 rows x 10 cols)").

Choosing a Destination

Moving to an Existing Tab

This is the default. Pick the destination tab from the Destination Tab dropdown, then type the upper-left cell where the moved block should land (e.g., D15). The cell reference uses standard Excel notation — a column letter followed by a row number.

Creating a New Tab

Select Create New Tab to move the cells into a fresh tab. You provide:

• New Tab Name — the name for the tab (up to 30 characters).
• Placement — whether the new tab appears After (default) or Before a reference tab.
• Reference Tab — the tab next to which the new one will be placed. Defaults to the last tab in the plan.

The new tab is sized to fit the moved block exactly. Row headers, column headers, column widths, number formats, and any grouped (spanning) headers from the source are all carried over automatically.

Row and Column Handling

These options control how the destination makes room for the incoming cells. They only apply when moving to an existing tab — when creating a new tab, both are locked to "Insert" since the tab starts empty.

Insert New Rows / Insert New Columns (default)

Blank rows or columns are inserted at the destination position before the cells are placed. Existing content is shifted down or to the right — nothing is lost.

This is the safest choice when the destination area already contains data.

Overwrite Existing

The moved cells are written directly on top of whatever is already at the destination. No rows or columns are added. Any content in the destination range is replaced.

Use this when you know the destination area is empty or when you intentionally want to replace its contents. When both row and column handling are set to overwrite, the tool will ask you to confirm before proceeding.

Tip: You can mix modes — for example, insert new rows but overwrite existing columns, or vice versa. This is useful when the destination tab has the right columns already but you need more rows (or the reverse).

Destination Size Requirements

When using overwrite mode, the destination tab must already have enough rows and columns to fit the block. If it doesn't, the tool will tell you how many are needed and suggest switching to insert mode.

Preserving Row and Column Headers

Two checkboxes let you carry over the source headers to the destination:

• Preserve source row headers — copies each source row's name to the corresponding destination row.
• Preserve source column headers — copies each source column's header text to the corresponding destination column. If the source has grouped (spanning) headers that fall within the selected range, those are copied too.

Both are off by default. Turn them on when the destination rows or columns are blank or generic and you want them to match the source.

Note: When creating a new tab, headers are always preserved regardless of these checkboxes — the new tab is built to mirror the source structure.

Formulas

Formulas within the moved block are automatically updated to reflect their new location, the same way a cut-and-paste would work. References between cells inside the moved block stay intact. References from outside cells pointing into the moved block are not updated — those cells will need manual correction.

What Happens to the Source Cells

After a successful move, the original source cells are cleared. They remain in the grid as empty cells — no rows or columns are deleted.

Same-Tab Moves

You can move a block to a different position within the same tab. When using overwrite mode on the same tab, the source and destination ranges must not overlap — the tool will reject the move if they do.

When using insert mode on the same tab, the tool automatically accounts for the fact that inserting rows or columns may shift the source block's position.

Errors and Recovery

• If a required field is missing or a cell reference is malformed, the tool shows a message explaining what to fix. The dialog stays open so you can correct the input.
• If the move fails for any reason, an error message is displayed. The Move button is re-enabled so you can try again or cancel.
• A version checkpoint is always saved before the move begins. If the result isn't what you expected, use the Versions panel to revert to the checkpoint labeled "Before Move Range (checkpoint)"

Getting Started

Adding one or more queries to your model involves two steps, the first of which only needs to be done once:

1. Create a DataSource
2. Use the DataSource via a CFSQL function call.

Creating a DataSource

This a specially-permissioned feature. Ask your account system administrator (or the ClearFactr Customer Success team) about it.  If you have permissions to this feature, the DataSource Editor will appear on the Developer menu visible on any open model. Select the item and you'll see the following:

Click here to learn more about each section of the tool.

You only need a single person on the team (with perhaps a backup) to create and manage your DataSources. All other users can make use of them, as described below:

Using a DataSource

ClearFactr's propriety CFSQL function is the connector between the details of your model and the data in your Cloud Data Warehouse. You can certainly write one by hand, but it may be easier to use our Query Builder to do it for you. Yes, you can think of it as a "wizard for CFSQL".  Once you get your query dialed in, and tested, via the Query Builder, you just commit it back to your chosen cell, and the results come into the grid. If you ever want to change the behavior of the query, just double-click the cell as if you're editing a formula, and the Query Editor will open with your CFSQL configuration already in place. Notice we said "behavior" of the query -- not the inputs. The most powerful thing you can do with this feature is to have cell values from your model, even those computed or derived by other queries, drive your chosen CFSQL function. In other words, there's incredible power in making these things highly dynamic and interactive.

To get started, right click on a cell and select "Insert --> Query" from the context menu. That will bring up the Query Builder, where the very first step will be to select a DataSource.  Here's the Query Builder:

Click here to learn more about each field.

A bit of strategizing around how to best use the API for different types of situations — and figuring out which one most closely matches your own — will help guarantee your solution will perform at its best, and endure.

QUICK TIP

If you're simply looking for the endpoints to the API, they're here. The purpose of this document is to help decide which endpoints to call, when, and why.

Continue reading...

Relevant Case Studies

• Transparency and Efficiency In Public Finance