Documentation

What's possible

A tour of what Locra can do and where to find each feature in the app. For the individual steps you put on the canvas, see Nodes.

The canvas

You build a workflow on the canvas. Each node is one step, and wires carry tables from one step to the next. Select a node to set it up in the Attributes panel on the right.

Adding nodes

• Add-node menu. Right-click the canvas, or click the + next to a node's output. A node added from + is wired up for you.
• Command palette. Press ⌘K (Ctrl+K on Windows) for one search box over nodes, actions (Run, Tidy, Share, Version history, Export…) and the sources on this machine.
• Names from other tools. Both searches understand the vocabulary of Alteryx, KNIME, Power Query, Tableau Prep, Dataiku, Flowfile, SQL/pandas and GIS apps. A match shows a chip such as KNIME: GroupBy, so you learn the Locra name. See Coming from….
• Suggestions. Drag from an output to an empty spot on the canvas. Locra proposes a likely next step, already wired. Press Tab to accept it, or Esc to dismiss it.

Editing

• Undo and redo cover every change to the graph: ⌘Z and ⇧⌘Z, or the toolbar buttons.
• Copy, paste and duplicate a selection with ⌘C, ⌘V and ⌘D. The copy is independent and runs on its own.
• Regions are coloured boxes with a title and notes, drawn behind a group of nodes. Select nodes and press ⇧R, or use the toolbar ⋯ menu → Draw → Region.
• Notes on a node. Press C to add or edit a comment on the selected node.
• Tidy in the toolbar (⇧A) lays the graph out left to right, with each branch in its own lane.
• Edit the code. Every node is Python underneath. Select a node, open the Code tab under the canvas and click the pencil to edit its code by hand. Revert to generated code in the Attributes panel brings the generated code back. A source node's code is read-only.

Hints and shortcuts

• The diagnostics chip in the toolbar lists problems Locra spots in the graph, such as a disconnected node or a join with no key. Some come with a one-click fix. Click one to jump to the node.
• When several fields pick from the same columns, a column that is already used elsewhere shows greyed out with used by …. You can still pick it.
• All shortcuts are listed, and can be changed, under the user menu → Keyboard shortcuts.

Connect data

Sources live in the Drones panel on the left. A drone is a small helper program that runs next to your data and reads it in place. You don't copy files into Locra first.

• Files. Drop a file on the canvas, or click + in the Drones panel header. CSV and TSV, Excel, Parquet, JSON, XML, SQLite and geo files are supported. See CSV Reader, Excel Reader, Parquet Reader and Geo Reader.
• Folders. Drop a folder to get a Directory source that lists its files. Feed it to a loop to process every file.
• Databases. One connection to PostgreSQL or MySQL serves all of its tables. Expand it in the Drones panel and drag out the table you need (DB Reader).
• Cloud and web. S3, Snowflake, Salesforce and Strava come from the same Add data source dialog. To read a web page, choose Web Page, then a table (Find tables), repeating items, contact details or the whole page (Web Page). Tick Render with JavaScript for a page that builds its content in the browser. Use REST Fetch for any URL or API.
• Used and Available. The Drones panel lists this project's sources under Used, and sources you added in other projects under Available. Drag an available source onto the canvas to use it here. A status dot shows whether each source is online.
• Context data. The Context Data section of the add-node menu has open datasets for site analysis: Overture Maps (places, buildings, roads), Population (Kontur), US Census (ACS), OSM Overpass and EU Parcels. These download from the internet, and the Census one needs your own API key.
• Data on another machine. A drone can run on another computer on your network. Click the WS item in the status bar at the bottom of the window, then Copy command. Run that command on the machine that holds the data. The drone program has to be installed on that machine.

No data yet? Generate Series and Constant Table make rows from scratch.

Run and preview

Runs happen on your machine. Each node's output is saved in a local cache inside the project, so a run only redoes the steps that changed.

• Run is in the toolbar, or press ⌘↵. Its menu also has Run all (force), which ignores the cache, and Dry run.
• Run states. A badge on each node shows whether it is fresh, stale (changed since its last run), running, or failed. Blocked means something upstream failed or a Gate held the data back. Email, Slack and HTTP Request nodes always run.
• Failures stay local. A failing node stops only the steps that depend on it. Other branches still run. If some nodes aren't set up yet, choose Run configured part to run the rest.
• The output dock under the canvas shows the selected node. Data is a sortable table, Metadata lists each column's type and display format, Code shows the node's Python, and Activity is the project log. Chart, Map and Report appear on the nodes that produce them.
• Column stats. In the Data tab, the chart button turns on a summary above each column: type, nulls, distinct values, min and max, and a histogram. The Parse… button on a text column turns it into dates, numbers or other types.
• Data bigger than memory. Sorts, joins and aggregations that don't fit in RAM spill to disk instead of failing.
• Dry run tests your outputs without touching the real destinations. Files go to a throwaway folder, database writes use a temporary table, and Email, Slack and HTTP steps check everything, then skip the send. You can dry-run the whole workflow, one output node, or one loop.

Selecting a node or editing its settings never writes to a real destination. Writers and senders only act on an explicit Run, or when you press Re-execute node in the Data tab. A Dry run writes to a throwaway target instead.

Loops and functions

Loops and named functions are frames on the canvas that hold other nodes. Select some nodes and press ⇧L for a loop or ⇧G for a function. You can also draw an empty one from the toolbar ⋯ menu → Draw.

Loops

• For each item. Wire a table, a folder or an S3 listing into the loop. The nodes inside run once per row or file. Inside the loop, a setting can say ${{ item.name }} to use the current item's value, for example in a file name or an email address.
• Collect results. Each output is either combined into one table (Union) or written once per item (Fan-out). Continue on error keeps going past a failing item, and Items at once runs several items in parallel.
• Iterate until done. A seed table goes into the first pass, and each pass feeds the next. The loop stops when a pass returns no rows, or when it reaches Max iterations.

There is no limit on the number of items. Use Current item and File inside a loop to read the item itself.

Named functions

A named function groups a part of the workflow into one box with its own inputs and outputs. Collapse it to keep a big graph readable. A collapsed function can still be run. See loops and functions on the Nodes page.

Formulas and finance functions

Formulas are SQL. You type them in Add Column, Multi-field Formula, Multi-row Formula, a Filter condition, or a full DuckDB Query. Write a column by its name, or in double quotes when it has a space: Price - Cost, "Unit Price" * 1.23. Conditions can be written IF x > 0 THEN 'Yes' ELSE 'No'.

Excel's finance functions work in every one of these, by their Excel names and with Excel's argument order. Money you pay out is negative, as in Excel, so the monthly payment on a 250,000 loan at 5% over 30 years is PMT(0.05 / 12, 360, -250000), which gives 1342.05.

• Loans and annuities. PMT, IPMT, PPMT, CUMIPMT, CUMPRINC, ISPMT, PV, FV, NPER and RATE.
• Rates and growth. EFFECT, NOMINAL, RRI (compound growth rate) and PDURATION.
• Depreciation. SLN, SYD, DB and DDB.
• Fractional prices. DOLLARDE and DOLLARFR.
• Cash flows. NPV, XNPV, IRR, XIRR, MIRR, MXIRR and FVSCHEDULE.

The cash-flow functions take a whole column. Where Excel takes a range, you write list(column ORDER BY period), so in a DuckDB Query SELECT NPV(0.08, list(cashflow ORDER BY period)) AS npv FROM _input gives the net present value of the table. For one value per project, use Aggregate: group by the project and pick NPV or IRR as the operation, with the period column and the rate on the row. In Add Column, IRR(list(cashflow) OVER ()) puts the same value on every row. When a calculation has no answer, for example an IRR of flows that never change sign, the result is empty rather than an error, so the rest of the run carries on.

Start from the add-node menu. Right-click the canvas and type the function, such as PMT, NPV or IRR, or what you want to work out, such as loan payment, depreciation or CAGR. The Finance section lists one row per function, and picking one adds a node with the formula already written: an Add Column for most functions, an Aggregate for the cash-flow ones. The formula uses the argument names as placeholders, for example PMT(rate / 12, nper, -principal). Replace each with one of your columns or a number.

Alteryx's names (FinancePMT, FinanceNPV and the rest) work too when you type them. The cash-flow ones take a list, as above, where Alteryx lists the values one by one. Not available yet: Excel's bond, coupon and Treasury-bill functions, and VDB.

Data quality

You can check data as it flows. Choose whether a broken rule should stop the run, skip part of the workflow, or only be reported.

• Assert fails the run when the data breaks a rule: not null, unique, in a set, in a range, matching a pattern, fresh enough, a row count, or your own SQL. It checks every rule first, then names each one that failed and how many rows broke it.
• Expectations scores the same kinds of rules and never fails. You get one row per rule with its pass rate.
• Gate lets data through only when a condition holds. If it doesn't, the steps after it are skipped and the run still succeeds.
• Compare Tables diffs two tables cell by cell. Flag Duplicates marks repeated rows, and Distinct removes them.
• Matching records. Fuzzy Match pairs similar keys. For larger jobs, Blocking finds candidate pairs, Match Grouping clusters them, and Survivorship builds one golden record per cluster.
• Profiling. Describe, Column Profile and Outlier Flag.
• Bad values when converting. In Cast Types and Parse, each rule decides what happens to a value that won't convert. Error stops the run. Warn (the default) blanks the value and shows a count on the node. Ignore blanks it silently.

Maps and geospatial

Geometry is a normal column in Locra. You can read it, transform it and map it like any other data, and most of it works without an internet connection.

• Formats. Read GeoJSON, Shapefile (also zipped), GeoPackage, GML, KML/KMZ, GPX and FlatGeobuf with Geo Reader, and GeoParquet with Parquet Reader. Write GeoJSON, GeoPackage, Shapefile or GeoParquet with Write Geo File. Turn lat/lon columns into points with Make Point.
• Spatial operations. Spatial Join, Spatial Intersection, Buffer, Dissolve (or Aggregate's Union, Extent and Centroid next to your totals), Reproject, Spatial Measure and Voronoi.
• Hexagons. H3 Aggregate rolls points up into H3 hex cells.
• Trade areas. Trade Areas draws catchments around locations: radius rings, drive-time bands, demand-based areas or directional wedges.
• Addresses and roads. Geocoding, routing, drive times and stop ordering have a section of their own: Routing engine.
• Maps. The Map tab of a Map node draws features, choropleths, heatmaps, sized symbols, two-variable choropleths, 3D extrusions, clusters and flow lines.
• Offline basemaps. A world overview map ships with the app. The Map tab's basemap selector has Auto, Offline, Online and Off. Auto uses the online map when you're connected and your downloaded maps when you're not.

Road data, street-level address indexes and detailed basemaps are managed under the user menu → Offline map data. You need an internet connection to download them. After that, they work offline.

Routing engine

Locra ships its own routing and geocoding engines. They run on this computer, on road and address data you download once per region, so a thousand drive times cost nothing per call and need no internet connection once the data is installed.

Routing on the road network

• Five routing nodes. Route works out the road route between each row's start and end, with distance, travel time and the route line. Isochrone draws the area reachable from each point within a time or distance. Matrix gives distance and travel time between every pair of points, or from each start to each destination. Map-match snaps noisy GPS points onto the roads. Optimize stops puts stops in the order with the least total travel, for one or several vehicles.
• Modes. Car, bicycle, foot or truck.
• Drive-time catchments. Trade Areas uses the same engine for its drive-time bands, and Gravity Model can weigh locations by drive time or distance instead of a straight line.
• Road data per region. Under the user menu → Offline map data, search a country, state or region (OpenStreetMap extracts from Geofabrik) and build its road tiles. One download, then it works offline. A routing node picks one or more tile sets in its Attributes panel; a point is answered by the first selected set that covers it, so a few regions can be combined without rebuilding.
• Honest about coverage. A point outside every selected region, or more than 2 km from a road, is reported as uncovered with a warning rather than being quietly moved onto the nearest road somewhere else. A matrix with one unreachable point still answers for all the others.

Geocoding

• Offline at city level, out of the box. Geocode turns place names into points, and Reverse Geocode turns points into place, region and country, from a gazetteer that ships with the app. It knows local-language names and the short names people actually write, so "León" finds León de los Aldama and "Querétaro" finds Santiago de Querétaro, and a country column keeps namesakes apart.
• Street level with an address index. Build an address index for your region on the same Offline map data page, from the same download as the road tiles. Geocode then matches street addresses and house numbers, and Reverse Geocode adds street, city and postcode.
• Online, if you choose. Both nodes can also call an online geocoding service you opt into in their Attributes panel, for places the offline data does not cover.

You need an internet connection to download road data and build an address index. Everything after that, including every Route, Matrix and Geocode run, works offline.

Reports

A report is built on the canvas like the rest of the workflow. Each section is a node, a layout decides where the sections go, and the result is written as a PDF, an HTML page or a PowerPoint deck.

• Sections. Table Section, Text Section, Image Section, Chart and Map.
• Assemble and write. Report Assembly places the sections into a layout. Write Report produces the file. Choose PDF, HTML or PowerPoint in its Format setting. PowerPoint tables stay editable. The Report tab previews the result.
• Layout Designer. Design pages and tiles with a live preview. Open it from a layout in the Reporting panel on the right, or with Edit layout… on a Report Assembly node.
• Themes. A theme sets colours, fonts, logo, page size, header and footer. Create or edit themes from the Reporting panel.
• Number and date formats. Format Table sets how columns print, such as currency, decimals or dates. The project can also hold rules like "every column ending in _sales is in USD".
• Report kits. Pack a project's layouts, themes and formatting rules into one file, and import it into another project to reuse the look.
• Draft with AI. On Report Assembly, pick the tables to feature and describe the report. Locra builds the section nodes for you. Section nodes also have buttons to draft or improve their text. These need an account.

Outputs

Output nodes take results out of Locra. They run when you click Run. Previews and selections never trigger them.

• Files. Write CSV (choose the delimiter, header and quoting), Write Excel (several sheets in one workbook), Write Parquet, Write JSON, Write XML, Write HTML and Write Geo File. When CSV and Excel writers replace a file, they keep the old one as a .bak backup by default.
• Hand-offs between projects. Write Locra Table saves a table with its formats. Locra Table Reader opens it in another project.
• Databases and storage. Write to DB loads PostgreSQL, MySQL or SQLite. S3 Sink writes a table to S3, or uploads a file such as a finished report.
• Messages. Email (over your own SMTP server), Slack and HTTP Request for webhooks and APIs. An Email can use an HTML report as its body.
• Serve data. HTTP Endpoint serves a table as JSON at a local address while the project is open.
• Order of steps. Wait For holds a step until others finish. For example, it can send the Slack message only after the database write is done.

Scheduling

Today you schedule a workflow by deploying it to Locra cloud runs (next section). The workflow then runs on a schedule you set, with no need for your computer to be on.

Scheduling runs on your own computer, inside the desktop app, isn't available yet. For your own scheduler, export the workflow as Python and run that package with cron, Task Scheduler or any tool you already use.

Cloud runs

Deploy a workflow to run in the cloud on a schedule. Cloud runs need a Locra account and an internet connection.

• Deploy & schedule. Toolbar ⋯ menu → Deploy & schedule to cloud. The wizard first checks that every source can be reached from the cloud. Then you enter the secrets the run needs, choose how often it runs, set a timeout and size, and review.
• Sources on your network. A source that only exists on your machine or office network can still be read. Promote its drone, and the drone connects out to the cloud run. Nothing has to connect into your network.
• Dashboard. User menu → Cloud runs lists your schedules and their status. From there you can run one now, pause it or delete it, and read each run's history and logs. A schedule pauses itself after three failures in a row.
• Run outputs. The files each run produced can be downloaded one at a time or as a zip, including from runs that failed.

Secrets you enter for a cloud run are write-only: they are stored encrypted and never shown again.

Share a workflow

A share link lets someone see your workflow in a web browser, with no install. It shows the workflow only, not your data. Sharing needs a Locra account.

• Create a link from the toolbar ⋯ menu → Share…, or from a project card's menu on the start page. Before anything is sent, the dialog lists exactly what will be uploaded.
• Expiry and recipient. A link lasts from one hour up to seven days. You can limit it to one email address, and that person must then sign in with that address. The link is shown once, so copy it right away.
• What viewers see. The graph, each node's settings and its Python code. They can pan and zoom, but they can't edit anything. Your data, cache and connection details are never uploaded.
• Open in Locra. A viewer who has the app can click Open in Locra to import the workflow as their own local project.
• Manage links under the user menu → Shared links. You can see each link's recipient, expiry and views, and revoke it.

To hand over a whole project with no account involved, use a .locra archive instead: start page → project menu → Export…. See Projects.

Export as Python

Any workflow can be exported as a regular Python package. You can then run it without Locra, from a script, a notebook, a scheduler or a server.

• Toolbar ⋯ menu → Export as Python library…. Choose a folder and a package name.
• The package installs with pip. One call runs the whole workflow, and each node can also be called on its own.
• Secrets are never written into the package. They are read from environment variables, which are listed in the package's README and example environment file.
• The export report lists any node that couldn't be exported, along with warnings and the required packages.

AI features

AI is optional. Everything else in Locra works without it. With a hosted model, AI features use your Locra account and an internet connection. With a model on your own computer, they work offline. Either way, you control how much of your data they can see.

Where AI shows up

• Create with AI on the start page is the project wizard. Pick sources and describe your goal. The wizard plans a workflow for you to review, then builds and runs it.
• The Assistant pane on the right (toolbar Extend with AI) is a conversation about the open project. It answers how-to questions from these docs and can add or change nodes for you. You can undo each turn, and earlier conversations are kept.
• Code Gen writes a custom step from a description. If built-in nodes already do the job, it offers to insert those instead.
• Text nodes. Classify, Extract, Summarize and Generate use AI to write the code that processes your text.
• Suggest with AI in a node's + menu proposes next steps. Turn it on first under user menu → Privacy & Diagnostics.

Staying in control

• Review before it runs. AI-written code is held for your review before it runs. This is on by default, and the setting is under Privacy & Diagnostics → AI.
• What AI may see. Every source has a Send to AI as setting in its Attributes panel. Rows sends a few example rows. Schema sends column types and statistics only. Description sends only text you write. Nothing sends nothing. The strictest setting upstream applies to every step after it, and only you can change it.
• Models. Pick a provider and model from the status bar, or under user menu → LLM Settings. The hosted providers are Anthropic, OpenAI, Google and AWS. You can also use a model on your own computer or network: enter the address of an OpenAI-compatible server (LM Studio, Ollama, vLLM and similar) on the On this computer card. Locra then calls that server directly, and nothing goes through the Locra service.
• Budgets. User menu → Usage & budget shows token use and lets you set a limit per day, week or month. A ring next to the model switcher shows how close you are.

Drive Locra from other AI tools

Locra can run an MCP server, so an MCP client can list your projects, inspect a workflow, read node previews and start runs. It is off by default. Turn it on under Privacy & Diagnostics → MCP server. It only listens on your own machine.

Credentials

Passwords and keys don't belong in node settings. Store them once in the vault, under the user menu → Credentials, and refer to them by name.

• Variables are plain values you reuse, such as ${{ vars.region }}.
• Secrets are write-only values kept in your operating system's keychain, such as ${{ secrets.API_KEY }}. You can't read a secret back after saving it.
• Credentials are typed bundles, such as an SMTP login, used as ${{ credentials.name }}.
• Secrets in URLs. In REST Fetch, a URL can contain ${{ secrets.NAME }}, for example an API key parameter. The key is filled in when the node runs and is never saved with the project.
• Email. An SMTP credential has a security setting (STARTTLS, SSL/TLS or None) and an optional sender address, for when you send from a shared mailbox.

On macOS, the first use of the keychain after launch may open a system prompt behind the Locra window. The app shows a "Locra is paused" screen until you answer it.

Working offline

Locra is built to work without internet. Your data, the cache and every run stay on your machine. A few features need a connection, either every time or once to download data.

Projects

A project is a folder on your disk. It holds the workflow, the code for each node and a local cache of results. Locra saves it as you work, and the toolbar shows Saved or Unsaved changes.

• Start a project from the start page: a Blank project, Create with AI, or one of the ready-to-run example templates, which come with sample data.
• Version history. Locra checkpoints the project as you save and after each successful run. Open it from the toolbar ⋯ menu → Version history. Restoring never deletes later versions, and you can duplicate the project as it was at any checkpoint.
• Rename, duplicate, export. Each project card's menu has Rename, Duplicate…, Export…, Share…, Version history… and Open folder. Renaming changes the display name only, and the folder stays where it is.
• Move between machines. Export… saves the project as one .locra file. Open it with the start page's Open project card, or double-click it. The Python environment and cache are rebuilt on the other side.
• Import from Alteryx. Open project also accepts Alteryx workflows, apps, macros and packages. Known tools become native nodes, and comment boxes become regions. An import report lists anything that needs your attention. Import works offline.
• Activity log. The Activity tab in the output dock records what happened in the project, grouped by run, and you can filter it.
• Appearance. Switch between light and dark mode from the user menu.