Create reports

Have AI make a report with SQL and charts or write it yourself, choose who can see it, and share it

A report combines text, SQL, charts and maps. It uses the same format as the reports in the Showcase. Each report opens at queria.io/reports/<ID>, where the ID is the string of letters and digits the report gets when it is created.

You need to log in to create reports.

Ask AI to make one

Connect Queria to Claude or ChatGPT (Use from AI chat)
Ask in the chat what you want to know. The AI queries Queria’s data, saves the tables and charts to a private report and returns its URL
Ask in the same chat for any changes

To make changes from another chat, click “Ask AI to edit” at the top right of the report to copy a request, paste it into your AI chat and add what you want changed. Only people who can edit the report (members of the account that owns it) see this button.

Clicking “+” (Analyze with AI) in the header (“Analyze with AI” in the menu at the top right on narrow screens) shows how to connect and links to Claude and ChatGPT. Saved reports appear under “Your reports” in the account menu.

Write it yourself

Click “Write it yourself” at the bottom of the “Analyze with AI” screen. You can also open “Your reports” from the account menu (queria.io/accounts/<handle>/reports) and click “New report”
Write the content and click “Save”

Saving opens the report. Use “Edit” at the top right to make changes.

Reports for an organization account are created with “New report” on that organization’s “Reports” tab (“Write it yourself” creates a report for your personal account). Members of the organization can create them.

Public names are covered in Give a report a public name.

After picking a point in Area Analysis, press “Save as report” to open a new report with a map block (Add a map) holding that point and area. Press “Save” to keep it as a private report.

Fork a published report

Open a public report and click “Fork” at the top right. The editor opens with a new report that holds the same content. Change the area codes in the SQL or the title, then click “Save” to keep it as your own report. A saved report is private by default.

A forked report shows a link to the report it came from (“Forked from …”). The link disappears if the original report is no longer public
The original report shows how many times it has been forked next to “Fork”
Images in the body are not copied. Charts are drawn again from the SQL
Only public reports can be forked. Members-only and private reports do not show “Fork”

Writing the content

Write the content in Markdown. The front matter at the top holds the title, summary and the datasets the report uses. Write SQL in code blocks.

---
title: Population by prefecture
description: Lists the population of each prefecture
tags: [population]
datasets:
  - queria/e_stat as e_stat
---

## The most populous prefectures

```sql
SELECT ...
FROM e_stat.<schema>.<table>
```

title and description (the summary) are required. A report without either can’t be saved
For how to write charts, see Draw charts and maps
SQL can only reference datasets listed under datasets. Write each as <handle>/<dataset> as <alias> and use the alias in SQL
The report can’t be saved if a listed dataset isn’t used in SQL, or if SQL uses a dataset that isn’t listed
format is the version of the writing format. If you leave it out, the latest version is used, and saving adds the current version to the front matter (for example format: 1). Saved reports keep the version they were saved with, even after a newer version comes out
The report’s author is shown as the account that owns the report. The published and updated dates also come from when the report was actually published and saved. An author or publishedAt in the front matter isn’t used for display. tags is optional too

Add a map

A map code block shows, on a map, the population and households living around a point (inside a circle, or within a walking, cycling or driving time), their age mix, household types and housing, and the land prices in the area. Readers can click the map, or search in the box at the top left of the map, to move the point and recount on the spot. The box finds stations and place names by their Japanese name (for example 新宿 or 吉祥寺), and Japanese addresses that start with the municipality (for example 新宿区西新宿2-8-1). An address moves the point to its house or block where the area uses residential addressing (住居表示), and to its town or chōme otherwise. The same search box is on the area analysis screen. “Open in area analysis” opens the same point in area analysis.

```map
type: around
lng: 139.393896
lat: 35.679414
radius: 1000
caption: 1km around Hino Station
```

The content is YAML. For type: around you can write lng / lat (longitude and latitude, numbers within Japan), radius (whole metres, 100–3000), walk / bike / car (travel time in minutes), show (sections to show), layers (layers to overlay) and an optional caption. Any other key stops the report from saving
Population is counted by splitting each census town block (chome) by the share of its area inside the range
The share of children and of people aged 65 and over, and the shares of household types and housing, are shown next to the same figures for a whole municipality. The municipality is the one holding the most of the range’s population (a ward, in a designated city), and its figures are the census values for the whole municipality as they are
The datasets the map uses do not need to be listed in datasets
On a report that uses only public data, readers first see the map’s numbers from when the report was saved. When a reader moves the point, the map recounts on the spot
Land price points start hidden on the map. With Pro, press the “Land prices” button above the map to show them. Without Pro, land prices appear only in the report

Choose what to show

List the sections you want under show: age mix (age), household types (households), housing (housing) and land prices (land_price). Without show, every section is shown. Total population, households and the list of town blocks are always shown. Sections you leave out are not counted, so the map appears sooner. Choosing sections is a Pro feature. Anyone can read a report that chooses them.

Household types split census private households into one person, couple only, couple with children, single parent with children, and other, together with the number of people per household. Housing shows tenure (owned, private rented, public or UR rented, company housing and so on) by the number of private households living in housing, and building type (detached, apartment buildings by number of floors, row houses and so on) by the number of main households.

```map
type: around
lng: 139.393896
lat: 35.679414
radius: 1000
show: [age, land_price]
```

With Pro you can choose the same sections on the area analysis screen with “Sections” at the top right. The choice stays in the URL, so you can share it as it is. On the free plan every standard section is shown.

Travel-time areas (Pro)

Write one of walk (5, 10, 15 or 20 minutes), bike (5, 10 or 15 minutes) or car (10, 15, 20 or 30 minutes) in place of radius to count inside the area you can reach by road in that time. Only accounts on Pro or an organization plan can write a travel-time area. If the plan ends, saved travel-time areas stay and you can still edit the report. Pro is needed only to add a travel-time area or change its settings.

```map
type: around
lng: 139.393896
lat: 35.679414
walk: 10
radius: 1000
caption: 10 minutes' walk from Hino Station
```

The saved travel-time results can be seen by everyone, including free accounts and people who are not logged in
Only people on Pro or an organization plan can move the point and recount by travel time. When anyone else moves the point, the map counts inside the radius circle (1 km if radius is not written)
Many maps on one report make the report slower to open

Put SQL results on a map

Without type (or with type: map), the results of the report’s sql id= blocks become layers on a map. Each row is placed by an area code column or by longitude and latitude columns.

```map
type: map
caption: Population by municipality, with shops
layers:
  - from: pop
    area: city
    code: lg_code
    color: population
    label: city_name
    name: Population
  - from: shops
    lng: lon
    lat: lat
    name: Shops
```

from is the name of a sql id= block. Layers are stacked in the order written, later ones on top
Place a layer with either area and code, or lng and lat
- area is prefecture, city or small_area (town block), and code names the column holding that area code: 2 digits for prefectures, 5 for municipalities (6-digit local government codes also work), and the census 9 or 11 digits for town blocks. Codes stored as numbers that lost their leading zero still work
- lng and lat name the longitude and latitude columns
color names a numeric column to colour by, label a column shown on hover, and name the legend entry. All three are optional
The map centre (lng / lat) and zoom are optional. Without them the map fits all the data
The boundary datasets do not need to be listed in datasets
sql id= names cannot start with __ (the map uses them)

Count around a point on the map

Add around: to the block to attach the trade area report. Your own SQL results, such as shop locations, stay on the map while the population around the point is counted.

```map
type: map
caption: 1km around Hino Station
layers:
  - from: shops
    lng: lon
    lat: lat
around:
  lng: 139.393896
  lat: 35.679414
  radius: 1000
```

around: takes lng / lat, radius, walk / bike / car and show, with the same meaning as in type: around
A map with around: is framed on the point, so lng / lat / zoom cannot be set on the map itself
type: around above is a shorthand for this form and produces the same map

Let readers choose values

An input code block puts a select box or a number field where you place it. In the SQL, charts and maps, write ${name} to insert the chosen value. When a reader changes the value, the report reruns the SQL with it and redraws the charts and tables.

```input
name: city
label: City
options:
  - { value: "13229", label: Nishitokyo }
  - { value: "13201", label: Hachioji }
```

```sql
SELECT * FROM e_stat.<schema>.<table>
WHERE lg_code = ${city}
```

name starts with a lowercase letter and uses lowercase letters, digits and _. label is shown next to the input; without it, name is shown
options makes a select box (up to 200 options). A plain list of values also works (options: [2020, 2015])
min and max make a number field. step sets the increment
default is the value selected at first. Without it, the first option or min is used
In SQL, string values are inserted quoted ('13229') and numbers as they are. You can use them in sql id=<name> blocks too, so every table, chart and map layer built from that view changes together
In a chart, a reference inside text such as "${city} population" inserts the option’s label (Nishitokyo)
In a map (map), you can use them for lng / lat / radius / zoom / walk / bike / car. Saving checks that the map can be built for every option, and fails if one cannot
Saving fails if ${...} names something that no input declares

The chosen values stay in the report URL (for example ?city=13201), so sharing that URL opens the report with the same values. A value in the URL that is not one of the options or is out of range opens with the default value instead.

Saved chart results are only for the default values. When a reader picks other values, the SQL runs on the spot. In a PDF export, each input is replaced by the chosen value as text, such as “City: Hachioji”.

Emoji and search settings

Set these with “Emoji” and “Show in search engines” in the editor, or write them in the front matter. Both do the same thing.

emoji: "🏫"     # The report's emoji. Defaults to 📊
search: false   # Keep the report out of search engines and the Showcase. Defaults to showing it

The emoji appears on the card image shown when the report is shared on social media, and in the list of other reports by the same author at the end of a report. Write exactly one emoji
Only public reports appear in search engines and the Showcase, where anyone can find reports others have published by keyword or dataset. Keywords also match the author’s name. The default order is “Recommended”, which weighs the number of stars against how recently the report was published. You can star the reports you like. With search: false, a public report stays out of search results and the Showcase (anyone with the URL can still open it)

What the SQL can read

A report’s SQL can read only the datasets listed under datasets. It can’t read files the reader uploaded or URLs on other sites.

Each block can hold a single SELECT statement (one trailing ; is fine). Several statements separated by semicolons are an error. When you need an intermediate result, use WITH, or write it in a sql id=<name> block and refer to it as <name> from other blocks. To show SQL that can’t run, put it in a sql run=false block: it is displayed as code and not run.

Visibility

Visibility	Who can see it
Private	Only you
Members only	Members of the organization that owns the report (only organizations on an organization plan can choose it)
Public	Anyone (no login needed)

Members only is an organization feature: it can be chosen only for reports of organization accounts with an organization plan. If the plan ends, reports that are already members-only stay as they are.

New reports start as private. Save and check how the report looks, then change the visibility to “Public” to share it.

A public report can only use public datasets.

Give a report a public name

Enter a name in “Public name (optional)” in the editor and save. A public report then also opens at queria.io/reports/<handle>/<name>. Names use lowercase letters, digits and hyphens (edit is not allowed).

Once a public report has a name, the URL with the name is its main URL. Opening queria.io/reports/<ID> takes you to it
Private and members-only reports open only at queria.io/reports/<ID>, even with a name
You can change the name later, or clear it to remove it. After a change, the URL with the old name no longer opens

Chart results

When you save, the report’s SQL runs and the chart results are stored with the report. While the save button shows “Computing chart results…”, wait a moment, or choose “Open without waiting” to open the report right away.

Readers see the stored results immediately, with “Results from the author’s run” and the date under each chart. “Open in playground” opens that chart’s SQL in a new tab, where readers can rerun it on the current data or edit it. If the data has been updated since, the numbers may differ from when the report was written.

Under each chart, “Data” lists the tables its SQL reads. Each one opens that table on its dataset page, where you can check the columns and the source.

Readers can also filter, sort and pivot a table with the Filter, Sort and Pivot buttons above it. The conditions apply to every row of the table. The report itself doesn’t change. Removing all conditions returns to the author’s results.

Reports that use private datasets don’t store results. The SQL runs each time a reader opens the report.

Export to PDF

Press “Export to PDF” at the top right of a report to open your browser’s print dialog. Choose “Save as PDF” as the destination to save the report exactly as it looks now. Maps where you moved the point and tables you filtered come out in that state.

The PDF includes the report’s URL, when it was exported, and the date of the chart results. The site header and buttons are left out. If you’re using the dark theme, the report switches to light only while it exports.

Exporting to PDF is a Pro feature. The button carries a Pro badge, and on the free plan it opens the pricing page.

Limits

Reports can’t include images
The content can be up to 200KB. There is no limit on the number of datasets a report uses
An account can hold up to 500 reports

Create reports from the CLI or AI

Turn a Markdown file into a report with queria report create report.md, or from an AI assistant with the MCP tool create_report. See the CLI reference and the MCP tools reference.

Delete a report

Click “Delete” in the editor. A deleted report can’t be restored. Its public name can then be given to another report.