Uploading a file and registering it as a table

What you will take away from this lesson

501 made the argument. This lesson is the mechanics, done once on a real file: the November price sheet from Blue Harbor Wholesale, four hundred rows, seven columns, the kind of attachment that used to wait weeks for a table.

There are two halves. Getting the file into the library, which a person does in the portal or the agent does in one call, and registering it, which turns the file into a table with a name you can write in a FROM clause. Both take minutes. The part worth learning carefully is what the platform tells you back, and the small set of files it refuses.

Learning Objectives

01Upload a file to the resource library with the fields that make it findable (display name, description, category, tags), on the tab that decides who sees it: My Resources, your persona, or Global.
02Know the Excel rule: export the sheet as UTF-8 CSV, one sheet per file, header row first, before uploading.
03Register from the file’s own page or by one sentence to the agent, and read what the registration answers with: the qualified name, the columns, and a sample statement with the cast.
04Find every registered table on the Scratch Tables page (search by name, facets by connection and by kind of file) and open one.
05Recognize the three things a file can be refused for and take the repair, which writes a corrected version through the file’s own version history.

Where this lesson sits

The second lesson of the 500 series, and the first hands-on one. It takes the supplier price sheet from an attachment to a table with a name, and covers the files the platform turns away.

500 Series: Spreadsheets as Tables

Open index

The 500 series assumes the asset mechanics from the 300 series and the knowledge loop from 206. It ends where the 600 series begins: the point at which a monthly file needs more than a join.

Resource or asset

Plexara stores two kinds of file, and both register the same way. A managed resource is something a person put in the library: reference material, uploaded with a description so others can find it. An asset is something the agent produced and saved, with the calls that produced it recorded as provenance. A supplier’s sheet is a resource. A CSV the agent exported from a warehouse query is an asset, and it can be registered too, which is how one query’s result becomes a table another query joins against.

Two kinds of stored file, one way to register them

A managed resource
What it is
A file a person uploaded as reference material, or one the agent filed on their behalf. It has a description, a category, tags, a scope, and a version history.
For example
The supplier’s price sheet. A report template. A brand file. A data dictionary somebody wrote.
Where it lives
The Resources page, on the tab that decides who sees it.
An asset
What it is
A file the agent produced and saved: an exported CSV, a dashboard, a report. It carries provenance, the calls that produced it.
For example
A CSV the agent exported from a warehouse query. The margin dashboard built in 504.
Where it lives
The asset portal, covered in the 300 series.

A CSV of either kind registers the same way, from the same panel, with the same tool. The difference is who put it there and what the file knows about itself. The rest of this lesson follows a resource, because a supplier’s sheet is something a person uploads.

Uploading in the portal

The Resources page has a tab per library: My Resources, your persona, and Global. Upload from the tab you want the file to land in; the dialog states the destination and who will see it before you pick a file. The dialog asks for four things besides the file, and the description is the one that decides whether anyone finds it later.

The Upload dialog

The tab you are on: My Resources, your persona, or Global. The tab is the library the upload lands in, and the dialog says who will be able to see the file before you choose one.
Category: One of the six shelves (data, visual, templates, playbooks, samples, references) or a custom one. The price sheet is data.
Display name: What the library and every search hit print. Name the file for what it is, not the month it arrived, because the same file will hold next month’s sheet.
Description: What the file is and what reads it. This is the text search matches, so write the question somebody will ask: supplier cost per SKU, monthly, compare to the cost of record.
Tags: Lowercase labels for filtering the library: supplier, pricing, cost, monthly.

The portal takes a file up to 100 MB. Once it is in, the file has its own page with a Version history (every revision, who uploaded it, when, how large; any version can be downloaded or restored) and a Replace content control that uploads new bytes under the same name, which is how next month’s sheet will arrive.

The Upload dialog on the Resources page: a file picker, a category selector, display name, description, and tags fields, with a note stating which library the file will land in and who will see it. — The dialog asks for the file plus category, display name, description, and tags. The scope is not a field; it is the tab you opened the dialog from, and the dialog states it.

The Excel rule

Suppliers send spreadsheets, not CSVs. The library will store a workbook, but registration needs a header row and rows under it, so the sheet you intend to query is exported first. This is a thirty-second step and the one people forget.

Registering from the file’s page

A CSV resource’s page carries a Query as a table panel. It shows what is already registered over the file and offers the connections that can hold a new table. Registering is a connection, an optional name, and one button. The platform reads the file, takes the columns from its header, creates the table over the directory the file occupies, and shows the qualified name it can now be queried by.

Registering from the Query as a table panel

1
Open the file’s page
A CSV resource or CSV asset carries a Query as a table panel. It lists what is already registered over the file, with each table’s columns, and offers the connections you can reach that can hold one.
2
Pick the connection and, if you like, a name
The connection is scratch. The name is optional and defaults to a slug of the file name. Either way your persona is added as a prefix, because the scratch schema is shared by everyone granted the connection and a reader should be able to tell whose working table they are looking at.
3
Register
The platform reads the whole file, takes the header row as the column list, creates the table over the directory the file occupies, and records the registration. The panel then shows the qualified name and the columns.
4
Register again, when you need to
The control stays available. The same name on the same connection replaces the registration (that is how a table is moved forward in 505); a different name, or another connection, adds a second table over the same file.

The Query as a table panel on a CSV resource page, with a connection selector, an optional table name field, and a Register button, above a list of the tables already registered over the file and their columns. — The panel on the file’s page. Connection, optional name, Register. What is already registered over the file is listed underneath with each table’s columns.

The same thing by asking the agent

The agent does both halves in one turn. Handed the sheet and a sentence about what it is, it files the resource with a description and tags, then registers it, and reads you back the answer. The trace below is the real one from the demo tenant; the answer is worth reading closely because it is the same answer the panel shows, and it tells you the two things you need to write the join.

From then on the file is findable by anyone on the team. A search hit for it carries the table reference and the sample statement, so finding the file and querying it are one turn apart.

The same two steps as tool calls, with the real answers

What the agent calls. This is the exchange the agent has with Plexara on your behalf, shown for the technical reader. You ask in plain language; you never type any of it.

manage_resource action=create
  filename="supplier-price-sheet-2025-11.csv"  category="data"  content_type="text/csv"
  display_name="Blue Harbor Wholesale price sheet (November 2025)"
  description="Monthly supplier quote from Blue Harbor Wholesale: the unit cost they will
    charge from the effective date, per SKU, with minimum order quantity and lead time.
    Keyed by sku, which matches warehouse.public.products.sku. ..."
  tags=["supplier","pricing","cost","monthly"]
→ resource_id 71131796b81fbb5641bdcbb3df0ef238   size_bytes 23696   scope user
  reference mcp:resource:71131796b81fbb5641bdcbb3df0ef238
  uri mcp://user/d2927f77-2c52-4d0d-a521-76c84428f22a/data/supplier-price-sheet-2025-11.csv

manage_table action=register
  reference = mcp:resource:71131796b81fbb5641bdcbb3df0ef238
  connection="scratch"  table_name="supplier_price_sheet"
→ query_table  scratch.uploads.admin_supplier_price_sheet
  registration_id  reg_a9de2c4f449ca8d2f44809b4405dfe57
  columns  sku, supplier_name, unit_cost, currency, moq, effective_date, lead_time_days
  registered_by  [email protected]   stale false
  sample_sql
    SELECT * FROM scratch.uploads.admin_supplier_price_sheet
    -- every column is VARCHAR, so a join to a typed column casts:
    -- JOIN scratch.uploads.admin_supplier_price_sheet t ON w.id = CAST(t."sku" AS BIGINT)
  "Registered as scratch.uploads.admin_supplier_price_sheet on connection scratch.
   Every column is VARCHAR, so a join to a typed column needs a CAST."

Two things to read in the answer. The qualified name carries the persona prefix admin_, which the registrant did not type. And the sample statement shows the cast pattern against the first column because every registered column arrives as text; in this file sku is text on both sides (SKU-000001) and needs no cast, while unit_cost does before any arithmetic. The agent writing a file this way is capped at 10 MB; a bigger file goes in through the portal and the agent registers it.

The Scratch Tables page

A file’s page shows what is registered over that file. The scratch schema is shared, though, so the question a reader usually has is wider: what is registered here at all, by whom, and is it still current. The Scratch Tables page in the portal’s section list answers that in one list, and each row opens to a page of its own.

What a row on the Scratch Tables page carries

Qualified name: The name to write in a FROM clause, persona prefix included.
Connection: Which connection holds the table. A facet narrows the list to one.
The file behind it: The resource or asset the table reads, and a facet for which kind it is.
Columns, who, when: How many columns the table has, who registered it, and when.
State: Behind the file, when the file has a newer version than the table points at. Source deleted, when the file is no longer on the platform.

The scratch schema is shared, so the question “what is registered here” has to be asked of the platform rather than of one file at a time. This page answers it: every registration you may see, searchable by name, whichever kind of file each was built over. Unregistering is done here, on the tables you may drop. Registering stays on the file’s own page, because it needs the file.

The Scratch Tables page: a search box, facets for connection and kind of file, and a list of registered tables showing each qualified name, connection, source file, column count, registrant, and state. — One list of every registration. Each row names the table, the connection, the file behind it, its column count, and who registered it, with the state called out when a table has fallen behind its file.

A registered table’s own page: the sample statement with the cast a join needs, the columns with their types, the file the table was built from, and the directory it reads. — Opening a row. The sample statement with the cast, the columns with their types, the file it came from, and the directory it reads, at an address of its own.

Files that are refused, and the repair

Registration reads the whole file before it creates anything, and it refuses three things a spreadsheet export commonly carries. Each would otherwise produce a table that is created without error and answers with wrong rows, which is worse than a refusal. Each refusal says what is wrong, and for all three the platform offers to correct the file itself.

Three refusals, one repair

A line break inside a cell
Why it is refused
The query engine reads a CSV line by line, so a multi-line address or note tears one record into several. The table would be created without error and answer with rows made of fragments. The refusal says how many rows carry one and which columns they are in.
What the repair does
Each run of line breaks inside a cell becomes a single space and the cell is trimmed.
Lines ending in a bare carriage return
Why it is refused
The classic Mac line ending some spreadsheet exports still write. To a line-based reader the whole file is one record. A Windows ending is not this and costs nothing.
What the repair does
Each carriage-return line ending becomes a newline, so every record is on its own line.
Bytes that are not UTF-8
Why it is refused
A legacy code page arrives as replacement marks in every affected cell. A NUL byte is refused on the same ground even where the rest of the file is valid.
What the repair does
The bytes are read as windows-1252, a leading byte-order mark is dropped, and the file is written back as UTF-8 CSV.

None of the three is refused silently and none leaves anything behind: no table is created and no registration is recorded. The refusal offers the correction, which is one control in the portal (Save a corrected copy and register that) or repair=true on the tool call. The result is a new version of the file itself, written through the version history the file already has; the upload stays as the version before it and can be restored. Two things are refused with no repair offered, because no correction could be made on somebody’s behalf: a file whose rows have a different field count from the header, and a UTF-16 or UTF-32 export. Both have to be fixed where they were written.

The Query as a table panel refusing a CSV that cannot be read as a table, stating what is wrong with the file and offering a Save a corrected copy and register that control. — A refusal names what is wrong and offers the correction. Taking it writes a corrected version of the file and registers that; the version panel records why the file changed.

What is recorded

A registered table is readable by everyone granted the connection, so registering is treated as the consequential act it is. It requires the authority to change the file, and it leaves a record.

What the platform still does not know

At the end of this lesson the sheet is a table with seven text columns and a name. The platform knows the columns are called unit_cost and effective_date. It does not know what they mean, and neither does the agent, until somebody tells it.

Key terms

Five terms from this lesson: two portal surfaces, the prefix every table name carries, and the correction the platform offers for a file it cannot read.

Key Terms

Resource library: The portal’s Resources page: files people upload, filed by category on the tab (My Resources, a persona, Global) that decides who sees them. A file has a page of its own with a version history.
Query as a table: The panel on a CSV resource’s or CSV asset’s page that registers it: choose the connection named scratch, optionally a name, and press Register. It lists what is already registered over the file.
Persona prefix: The prefix added to every registered table name, from the registering person’s persona (admin_ in this lesson). It keeps one persona’s working table apart from another’s in a shared schema and tells a reader whose it is.
Scratch Tables: The portal page listing every registration you may see: qualified name, connection, source file, columns, registrant, and state. Search by name, facet by connection and kind of file, unregister from here.
Repairrepair=true: The correction offered when a CSV cannot be read as a table the way it is stored: a new version of the file written through its own version history, with the upload kept as the version before it.

502 - Uploading a file and registering it as a table