--- title: Create reports description: 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](https://queria.io/en/showcase). Each report opens at `queria.io/reports/`, 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 1. Connect Queria to Claude or ChatGPT ([Use from AI chat](/en/ai-chat)) 2. 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 3. 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. Saved reports appear under "Recent" on the signed-in home page and under "Your reports" in the account menu. ## Write it yourself 1. Open "Your reports" from the account menu (`queria.io/accounts//reports`) and click "New report" 2. 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](#give-a-report-a-public-name). After picking a point in [Area Analysis](https://queria.io/maps), press "Save as report" to open a new report with a `map` block ([Add a map](#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. ````md --- 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.. ``` ```` - `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](/en/charts) - SQL can only reference datasets listed under `datasets`. Write each as `/ as ` 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](https://queria.io/maps). ````md ```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. ````md ```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. ````md ```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. ````md ```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. ````md ```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. ````md ```input name: city label: City options: - { value: "13229", label: Nishitokyo } - { value: "13201", label: Hachioji } ``` ```sql SELECT * FROM e_stat..
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=` 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. ```yaml 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](https://queria.io/en/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) - The "Maps" and "Dashboards" tabs of the Showcase list public maps and dashboards, newest first. Keywords match the title and the owner's name ## 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=` block and refer to it as `` 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](/en/pricing). 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//`. 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/` takes you to it - Private and members-only reports open only at `queria.io/reports/`, 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 and try" 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](/en/pricing) 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](/en/reference/cli#queria-report) and the [MCP tools reference](/en/reference/mcp-tools#create_report). ## 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.