Connect a CSV or Excel import¶
Bring your own traffic counts to help Squoosh match AI shoppers to your visitors. Import a CSV, TSV, TXT or XLSX file, review its column mapping and resulting shares, then confirm what Squoosh reads.
A file import uses the numbers you supply. It does not fetch newer numbers from the original tool. Import a new file when you want to replace the previous counts for this connection.
The three-step wizard¶
- Choose. Open Data sources, choose the CSV / Excel import source, and drop a file or click to choose one. The limit is 4 MB (4,000,000 bytes). You can add a description of up to 500 characters, such as “GA4 export, sessions by device for August.” For an Excel workbook, Squoosh starts with the first sheet. A sheet picker appears after inspection when the workbook has several sheets.
- Review. Check the detected layout and confidence, then choose the column for each role. Set what the counts represent and how many days the file covers. Map any unrecognized labels and inspect the device, geography and channel shares, totals and coverage. The expandable sample section shows values from your own file. If Squoosh cannot detect the layout, choose it and the columns yourself, or go back and describe the file. Confidence is a suggestion, not proof that the mapping is correct.
- Confirm. Read the “Confirm what Squoosh reads” card, then select Import file. Confirmation requires a successful preview for the current mapping. Squoosh validates the file again before storing the aggregate counts.
Editing a column or alias automatically inspects the same file again using your mapping, without another model call. Replacing the file or choosing a different sheet clears the old preview. If inspection fails, correct the mapping or select Preview again. A server error does not require choosing the file again.
Three supported table layouts¶
The examples below use small illustrative counts. Use non-overlapping data from one period and one population. Repeated custom-layout buckets are added together after label mapping; this does not deduplicate overlapping users, repeat exports or duplicate order line items.
Wide table: GA4 Explore export¶
A wide table has one column per available dimension and a count column. It can contain just one dimension. In GA4, export an exploration with Device category and Sessions. GA4 supports CSV and TSV exploration exports. See Google's exploration guide.
# ----
# GA4 Explore export
# ----
Device category,Sessions
mobile,600
desktop,400Choose Wide table, Device column = Device category, Count column = Sessions, and counts = sessions. Leave Country and Channel as Not supplied. The preview shows 1,000 sessions: 60% mobile and 40% desktop. It cannot supply a geography or channel distribution from this file. Without a conversion count, it supplies no conversion rate.
Long table: Adobe Workspace export prepared for import¶
A long table has separate dimension, label and count columns. Adobe Workspace can download project data as CSV; export your channel table and keep the actual Visits metric. See Adobe's download guide.
For example, a table containing Marketing channel and Visits can be imported directly as a wide table. To combine several dimension tables in one long table, add a dimension column yourself. This is a prepared import table, not a claim about Adobe's native export header:
Dimension,Label,Visits
channel,Natural Search,400
channel,Paid Search,200
channel,Social Networks,100
channel,Email,100
channel,Referring Domains,100
channel,Typed/Bookmarked,100Choose Long table, Dimension column = Dimension, Label column = Label, Count column = Visits, and counts = visits. The channel labels become Organic Search (40%), Paid Search (20%), Social (10%), Email (10%), Referral (10%) and Direct (10%). Set days covered to the export's actual period. Keep subtotals out of the data; they would count the same visits twice.
Individual rows: why a Shopify orders export needs different data¶
The individual-row layout counts each row, or a weight column, toward a population you explicitly identify. It works for one row per session with a device, country or channel column. An optional converted flag can count converting sessions.
A Shopify orders export, including a prepared subset such as this, has a different population:
Order ID,Shipping Country,Referring site,Total
1001,US,google.com,49.95
1002,GB,example.com,24.95There are two order rows. Total is money, not a session count; Shipping Country describes orders, not all visitors. Inspecting it can help identify columns, but keeping the truthful population orders prevents import for traffic calibration in this release. Squoosh cannot derive a session conversion rate from it. Do not relabel orders as sessions to get past validation. Use a sessions or visits report from your analytics tool instead. Shopify exports can also repeat orders across line items, so counting rows need not count unique orders.
For a real session-row export, select Individual rows, map its dimension columns, and explicitly choose sessions. A weight is optional; without one, each row counts once. Only map a converted column when it actually identifies conversion in that session.
Labels and aliases¶
- Device: canonical labels are
mobile,desktopandtablet. Common equivalents such as smartphone, laptop and iPad are recognized. An unfamiliar device needs an honest mapping; a TV is not automatically a desktop. At least 80% of device count mass must be recognized. - Channel: canonical labels are
Direct,Organic Search,Paid Search,Social,EmailandReferral. Examples include GA4 Organic Social and Paid Social becoming Social, and Adobe Natural Search becoming Organic Search. Display, Unassigned and ambiguous campaign labels need your review. - Geography: choose an ISO two-letter country code, such as
US,DEorGB. Country names are normalized when recognized.otheris for an actual grouped remainder such as “Rest of world,” not a guess for missing geography. - Ignore: use only for structural totals, subtotals or blank rows. It is not a way to remove an inconvenient visitor group. Coverage retains unrecognized mass; ignoring labels does not create a smaller conversion denominator.
Unrecognized country and channel labels can remain as aggregate buckets. A dimension with insufficient recognized coverage may be omitted. The preview explains the omission; Squoosh does not invent a distribution for a missing dimension. Very small samples may also be excluded from shopper calibration even when the file is valid.
Population matters. Sessions and visits can provide traffic shares and a conversion rate when a matching conversion numerator exists. Users, visitors and pageviews provide traffic shares only. Orders and unspecified rows are rejected for calibration. Any optional conversion total must refer to the same population and period as the denominator.
Existing Squoosh template¶
The original template remains supported without column remapping:
dimension,bucket,sessions
device,mobile,600
device,desktop,400
conversion,total,30Its header must be exactly dimension,bucket,sessions. Use dimensions device, geo, channel or conversion, and total as the conversion bucket. The six channel labels above must match exactly. Duplicate dimension/bucket pairs are rejected. The template retains its 1 MB and 10,000-row limits. This example has 1,000 sessions and 30 conversions, a 3% session conversion rate.
Limits and troubleshooting¶
| Limit or message | What to do |
|---|---|
| Custom file over 4,000,000 bytes | Aggregate the data or remove unused columns before importing. |
| More than 50,000 rows, 64 columns or 500,000 cells | Reduce the table. All three limits apply independently. |
| A cell over 16 KiB or more than 2,000 distinct labels per profiled column | Remove long text and identifiers; aggregate labels first. |
| Excel expands beyond 40 MiB or contains more than 50 ZIP parts | Save a smaller workbook containing only the table you need. |
| Formula warning | Recalculate and save the workbook first. Squoosh reads saved values; it never evaluates formulas, macros or external links. |
| Invalid counts | Use non-negative whole-number counts. Properly grouped thousands are supported; percentages, currency values and fractional counts are not. |
| Preview required or file/sheet changed | Wait for the current inspection or select Preview again before confirming. |
| Too little recognized data | Correct genuine aliases or supply a better breakdown. Do not force unrelated labels into known groups. |
The upload cap leaves room for mapping and multipart framing under Vercel's 4.5 MB request limit. Preview lists show at most 50 bucket labels per dimension and up to five sample values per column. Totals are computed from the entire accepted table, not just those visible samples. Files cover 1 to 365 days, with 28 days as the default until you specify the actual period.
Privacy and storage¶
Squoosh processes your uploaded file to build the preview. Sample values from your own file are shown back to you, along with unmatched labels, so you can judge the mapping.
After confirmation, Squoosh stores aggregate counts and bucket labels, including canonical labels produced by the mapping. Unrecognized country or channel bucket labels may also remain in the aggregate data. It stores the file name, format, sheet name when applicable, layout, row count, column roles and types, coverage, declared population and period, formula flag, import time, and the description you type. Your workspace's integration readers can see the file summary and description. Avoid putting personal information into descriptions, file names or bucket labels.
The original file, raw input rows, column-header text, preview samples and alias dictionaries are not stored with the connection. The stored rows are compact aggregate counts, not a copy of each input record.
When you type a description, it is sent to a language model to suggest a mapping, along with column details and bounded sample values. An unclear layout can also trigger mapping assistance without a description. The whole file is not sent to the model. Assistance may be disabled or unavailable, in which case the wizard uses heuristics and your manual choices. Editing columns or aliases and committing an import do not call the model again.