Metric Export

The Data Export page exports any metric of your plants as a time series: from the feed-in of a whole portfolio down to one irradiance sensor, one turbine or one battery cell. You choose the plants, the metrics, the time range and the step, check the preview, and download a CSV file. Every export is also a link you can hand to Excel or a script.

This guide covers the page itself. The parameters behind every export link are described in the Metric Export API.

One Metric Collection

The export and the reports read the same metric collection. A metric has one name, one unit and one definition, wherever you meet it: in the report data picker, in a finished report and in an exported file.

The collection holds:

• the metrics Mirox ships, ordered by level — plant, inverter, combiner box, string, battery, wind turbine, sensor, meter, weather, market and more. The levels are listed under Available metrics;
• the metrics your organization defined itself under Metrics. In the picker they are grouped as My Metrics.

A metric marked Not validated under My Metrics cannot be exported until its expression validates.

The Three Tabs

Exporting Metrics

1. Choose the Plants

Under Plants, open the plant list and tick one or more plants; the portfolio list next to it adds whole portfolios. The lists are the same as in the navigation on the left: every row carries the type of the plant — solar, wind or battery — and what you chose appears as chips in the field. Plants and portfolios can be mixed; a plant that also lies in a chosen portfolio is exported once. You can export at most 50 plants in one file. With more than one plant you also choose whether the plants are combined into one column per metric or shown side by side — see Several plants. Plants in different time zones put the file on UTC — see Plant local time and UTC.

2. Add Metrics

Under Metrics, type what you are looking for into the search field — a name, a word of the description, a component or a unit, for example inverter dc. Every word you type has to occur somewhere in a metric: in its name, its id, the ids the previous export used, its unit, its level or its description. The best matches come first: a metric whose name starts with your words before one that only mentions them in its description. Enter adds the first match, the arrow keys move the choice, and Browse all metrics opens the whole collection by level, with the same search. energy_grid_daily finds Grid feed-in, so an id from an old link works too.

Every row says what the metric measures and at which steps it can be read. A row you cannot choose names the reason:

One export carries at most 20 metrics. The chosen metrics are listed below the search, in the order of the columns; drag a row to change it. Explanations above the list opens a description of every chosen metric: unit, how often it is measured, the steps and values it offers, and how several plants are combined. Download glossary (CSV) there gives you the whole collection as a file.

If the collection has no metric for what you need, Create metric opens the metric editor of the Reports page; Back to Data Export at its top brings you back with the plants, metrics and time range you had. For a one-off reading of the time-series store, add a MetricsQL query instead.

3. Choose Components

A metric of a component level — inverter, combiner box, string, wind turbine, sensor, meter, battery container, rack, module, cell or power converter — exports one column per component. Without a choice you get all components of the plant, 50 per page. To restrict the export, open the component button on the metric and choose the ones you need, up to 100.

This is how you export every irradiance sensor on its own, without averaging: add Irradiance per sensor and leave the component choice empty.

Hidden components are left out. Show hidden in the component dialog lists them, so you can choose one on purpose.

4. Set the Time Range

Under Time range and step, pick a preset or set your own start and end. The presets are Today, Yesterday, Last 7 days, Last 30 days, This week, Previous week, This month, Previous month, This quarter, Previous quarter, This year and Previous year. Without a choice, the export covers the previous month.

A range may start in 2020 at the earliest and span at most five years. A range that reaches into the future ends now.

5. Choose the Step

The step is the length of one row: 1 min, 5 min, 15 min, 1 h, day, week, month, quarter or year. Left on automatic, Mirox chooses a step that every chosen metric serves and that fits the range: 15 minutes up to two days, one hour up to two months, a day up to three years, a month beyond that.

Not every metric can be read at every step — see Steps and their limits. A metric that does not serve the chosen step is still exported, at its own step — see Metrics with different steps. Only a step at which a metric could have no row at all is greyed out and names that metric.

6. Choose the Values

For an energy or another counted quantity, choose under Values whether each row shows the amount Per interval or the Running total since the start of the range. All other metrics are exported As measured, and the list says how each row is formed — see Values.

7. Choose the Time Zone

Plant local time is the default; UTC is the alternative. See Plant local time and UTC.

8. Check the Preview and Download

The Preview shows the export as a chart or as a table. Below the time range, one line states the size: rows, columns, the approximate file size and duration. Notes under the preview tell you what Mirox did on its own, for example that a range was widened to whole days.

In the chart:

• The eye at the start of every metric and query row hides its series in the chart and the table, and shows it again. A hidden series stays in the download and in the link; the setting is part of the page's address, so a shared link shows the same view.
• Clicking a name in the legend does the same; Shift-click shows only that series. Legend and eyes always agree.
• Drag across the chart to zoom into a range; double-click zooms out again. Zooming changes the view only.
• The tooltip lists up to ten series, the largest value first, and says how many more there are.
• A long range at a fine step has more points than a browser can draw. The chart then shows a coarser resolution and says so in an orange note — The chart shows 1 h resolution so it stays readable; the table and the export keep 1 min — or, where no coarser step is offered, combines several rows into one point. The table, the download and the link always keep the step you chose.

Under Export options, choose the CSV separator, the decimal separator, the timestamp format, the language of the column names and the Column headers: Names (for people) or Ids (for scripts). The timestamp format also changes the dates in the table, so the preview shows what the file will carry. Then:

• Download CSV saves the file.
• Copy API URL copies the same export as a link. Try it out prepares an API token and gives ready-made commands for the terminal and for Python.
• Save as template keeps the selection as a template.

MetricsQL Queries

Next to the metrics of the collection, the Metrics tab takes raw queries in MetricsQL, the query language of the platform's time-series store — the language the metrics of your organization and Grafana use. A query is for what the collection has no metric for: a series the store carries, a combination of series, a function of them.

1. Click MetricsQL under the metrics to open the query field.
2. Type the query, for example sum by (inverter_id) (powerplant_inverter_power_ac). While you type, the field proposes series names, labels and functions; Tab takes the proposal. Enter runs the query and adds it as a row; Shift+Enter starts a new line inside the query.
3. The row shows the query text on a code background and the chip MetricsQL where a metric shows its unit. The row's columns are one per series the query answers, as measured. The pencil turns the text into an editor in place: Enter saves, Esc cancels. Nothing else about the row changes.

What a query does and does not do:

• Mirox adds the chosen plant to every selector of the query, so the query never names a plant, a park or an organization. A query that carries such a label is refused, with the label named.
• A query is read at the step you chose — any step, from 1 min to a year — as a dashboard would read it: raw samples at that step, no value mode, no fold. Per interval and Running total do not apply to it.
• With several plants, every plant gets its own columns. Queries are never combined over plants.
• A query may answer at most 500 series on one plant; aggregate it, sum by (…) for example, when it answers more. One export carries at most 5 queries of up to 4 000 characters each, and the series they answer count against the size limits like every other column.
• In the file, the column is headed MetricsQL followed by the query, and when the query answers several series, by each series' labels: MetricsQL sum by (inverter_id) (powerplant_inverter_power_ac) {inverter_id="INV1"}. With Ids (for scripts) the header is expr1, expr2, … with the same labels. So a file with queries is told apart from a plain export by its first row.
• A query is not saved in a template. Remove the queries to save the metrics as a template, or define the figure once as a metric of your organization: it is then validated, has a name and a unit, and is offered to the reports as well.

Steps and Their Limits

Which steps a metric offers depends on what it is and how often it is measured:

A metric is never offered finer than it is measured: a wind turbine that reports every 10 minutes has no 1-minute values.

The step also bounds the range, because one column holds at most 180 000 values:

Steps of a day or longer always cover whole days, weeks, months, quarters or years. A range that starts or ends inside one is widened to the whole interval, and a note says so. Weeks start on Monday.

Metrics With Different Steps

Not every metric serves every step, and some serve only coarse ones: the performance ratio starts at the day, a market value exists once per month. The Metrics tab still puts them into one file:

• A metric with a coarser step than the file keeps its own step. Its value stands on the first row of each of its intervals — a day's figure on the row of its midnight, a month's on the row of its first day — and the rows between stay empty. The chart draws such a metric as points. An orange note above the preview names these metrics with their steps and offers Export separately: one link per step, every metric at its own resolution.
• A metric that serves only finer steps is read at the coarsest of them and combined into the file's step by the rule of its quantity: an energy is added, a reading averaged, a ratio recomputed from its halves, a state keeps its latest code. A note under the preview says so.
• Two cases remain refused: a figure per month, quarter or year has no row on a week file, and a monthly figure such as the Marktwert is never added or averaged into a quarter or a year, because that would not be the figure. Such a step stays greyed out and names the metric.

A template decides for itself with Metrics of another step: Lenient behaves like the Metrics tab, Strict refuses a link that names a step one of its columns does not serve. A template saved from the Metrics tab or created anew is Lenient; templates from before this setting are Strict. An export link written by hand is strict unless it says otherwise — see the parameter mismatch.

Values: Per Interval, Running Total, As Measured

Per interval is offered for energy only. A power, a temperature or a ratio has no "amount per interval", so these are always exported as measured.

The Warning Below 15 Minutes

A meter counts energy in whole steps, often 1 kWh. Within one minute a plant seldom produces a whole step, so an energy per interval at 1 or 5 minutes jumps between zero and one step instead of drawing a curve. Mirox warns when you combine the two and offers three ways out:

• Switch to the matching power metric, where the collection has one. Power is the right quantity for a fine curve.
• Use 15 min, the finest step at which an energy per interval reads well.
• Keep, if the meter steps are what you want to see.

Plant Local Time and UTC

Rows follow the local time of the plant, including daylight saving time. A day is a local day, so it has 23 or 25 hours when the clocks change, and a month is a local month.

• At steps shorter than a day, a column UTC offset stands next to the time. On the day the clocks go back, the hour between 02:00 and 03:00 appears twice; the offset tells the two apart.
• UTC as time zone puts all rows on the UTC calendar. Use it when the file goes into a system that expects UTC.
• Plants in different time zones share one time column, so such an export is always in UTC. The time zone choice is locked then and says why.

Several Plants: Combined or Per Plant

With more than one plant you choose between one column per metric for all plants together, and one column per plant.

Combined, each metric follows its own rule:

Component metrics are always shown per plant. A note under the preview names every metric that was shown per plant instead of combined.

Templates

A template is a saved list of metrics with its own defaults: step, time range, values, time zone, combined or per plant, and column headers. Each column can carry its own header text, so the file keeps its headers even when a metric is renamed later.

System Templates

Mirox ships eight templates, marked System. They cannot be changed or deleted.

The first five succeed the templates of the previous export. Their ids and columns are listed in the migration guide.

Your Own Templates

Save as template on the Metrics tab, or Create template on the Templates tab, stores your selection for the whole organization. A template holds up to 40 metrics and no MetricsQL queries. Open in Metrics loads a template into the Metrics tab. Metrics of another step decides what a link of the template does with a column that does not serve the requested step — see Metrics with different steps.

Templates are created, changed, converted and deleted by the organization role Admin. Everyone in the organization can use them.

A metric of your organization that a template uses cannot be deleted or given a new id. If a metric of a template is no longer available — it fell back to Not validated, for example — its column stays in the file, empty, so the positions of the other columns do not move.

Legacy Templates and Conversion

A template created before the Metric Export is marked Legacy. It is built on the previous metric set, and its link keeps working unchanged. New templates are always built on the metric collection.

Convert to new template creates a new template from a legacy one. The legacy template is never changed, so files and links that use it stay as they are.

1. Mirox shows which columns have a counterpart, whether the numbers are the same (exact) or the same quantity read in a better way (approximate), and which columns have no counterpart.
2. You give the new template a name and confirm.
3. Both links are shown. Excel keeps using the old link until you replace it.

A converted template exports days, like its source. A column whose metric has no daily value — frequency or power factor, for example — is not carried over; the dialog names the metric so you can export it on the Metrics tab.

API Builder

Choose a template and the plants, and adjust time range, step and file format if the template's defaults do not fit. The page shows the link and a preview of the data. Try it out prepares an API token and ready-made commands for that link. For a legacy template, the builder shows the previous link and offers the conversion.

A link with a preset such as Previous month always delivers the most recent complete period, which is what a workbook that refreshes itself needs. See Excel with Power Query.

When an Export Is Too Large

Mirox checks the size of an export before it reads any data. If the export is too large, nothing is exported, and the message offers what would fit: a coarser step, or a shorter range with the number of days named.

To export more, split the export:

• by time — one file per month or per quarter instead of one per year;
• by plant — one file per plant or per portfolio;
• by metric — component metrics in a file of their own, separate from the plant metrics;
• by page — for a plant with many components, export the components page by page.

Metrics that Mirox has to work out from several sources, such as Production (resolved), cost more than a plain meter reading. A template that carries such a metric reaches fewer plants and months per file. The size line below the time range tells you before you download.

Who Can Export What

• You export the plants whose measurements you may read: the job roles Operator, Technical Manager, Asset Manager and Viewer. A plant you cannot read is left out, and a note names it.
• Money metrics additionally need the accounting permission, which the job roles Operator and Asset Manager have. Without it, the column stays empty for that plant.
• The metrics of your organization are exported on every plant you can read, including plants shared with you through a cooperation. They are offered to every organization role except External.
• Outside the browser, an API token of the group Metric Export reads every export. It cannot change anything.

Old Links and Bookmarks

Links to the previous Raw Data tab and to the previous Metrics tab keep working: they open the Metrics tab with the same plants, metrics, time range and step. Where a metric has no counterpart, a banner says so and offers Copy original API URL, which still delivers it. A link to one of the five earlier system templates opens its successor.

Formulas are no longer edited in the app. See MiroxQL formulas.

Related Features

• Metric Export API — every parameter, error and limit of the export links
• Migrating to the Metric Export — old ids and their new metrics, and what changes
• Legacy Export API — the previous export links, which keep working
• Metric Export for Excel — recipes and Power Query
• Data Export FAQ — short answers to common questions
• Metrics — your organization's own metrics
• API Tokens — the Metric Export token