Data reference

​

Introduction

File from OneDrive imports CSV files stored in a Microsoft 365 account into Adriel through the Microsoft Graph API. A single connector reaches all three Microsoft drive surfaces — personal OneDrive, OneDrive for Business, and SharePoint document libraries — because Microsoft Graph exposes each of them as a drive behind one API, and the selected drive determines which surface is read. A common use case is a marketing or finance team that already maintains a regularly updated CSV file in OneDrive or a shared SharePoint library. On each scheduled refresh, the connector fetches the latest content of the configured file, parses it, and writes the rows into a per-data-source cache. Because the connector is free-format, the available fields are not a fixed catalog — they are the columns of the imported file. Numeric columns become metrics, and non-numeric columns can serve as either a metric or a breakdown. To connect this data source, see How to connect File from OneDrive to Adriel.

​

Data refresh strategy

File from OneDrive is a cache-backed connector. Data is not fetched live at dashboard load; instead a background worker syncs the file on a schedule into a per-data-source PostgreSQL cache table, and every widget, dashboard, or report reads from that cache. Cadence. The sync runs twice daily on cron 0 1,13 * * * — at 01:00 UTC and 13:00 UTC. Refresh mechanism. On each run the connector obtains a fresh Microsoft access token from the stored refresh token, downloads the configured file from the Microsoft Graph content endpoint, streams it into the CSV parser, and upserts the parsed rows into the cache table (SimpleFileCache, UPSERT strategy). A partial or failed refresh leaves the previous cached snapshot in place rather than emptying the table. Field visibility. New columns added on the OneDrive side become available after the next successful sync refreshes the cached field metadata.

​

Architecture levels

Microsoft drive → (optional folder) → File. Discovery walks these levels through Microsoft Graph:

1. Drive — the connected account’s available drives are listed from GET /v1.0/me/drives. Each drive is one of three types: personal, business, or documentLibrary (SharePoint).
2. Folder — an optional folder within the chosen drive can scope where the file is located.
3. File — the target CSV is located with the Microsoft Graph search API and pinned by its file identifier.

One data source binds to one file. To import a second file, create a second data source.

​

Date range limits

There is no platform-imposed date range, and the connector does not apply a date filter of its own (hasDateBreakdown = false). Date semantics come entirely from the file’s contents. When a column is mapped as the date field during setup, that column drives date-range filtering on the dashboard. When no date column is present, all rows are treated as a single snapshot set regardless of the dashboard date range.

​

Import model

Rather than issuing a query to an external system at widget load, this connector imports a file on a schedule and serves widget queries from its local cache. File selection. During setup the target file is located with the Microsoft Graph search API, which paginates results ($top=200 with $skipToken). An optional comma-separated filename filter (for example, report,monthly) narrows the search: each substring is combined with the file type into the search query (q='csv report monthly'). Once selected, the file identifier is persisted on the data source. Parsing. Files are parsed as CSV. The first row is treated as the header, and each header becomes an available field. Column data types are inferred from the parsed values (see Field type mapping). Caching. Parsed rows are written to a per-data-source PostgreSQL cache table (one table per data source). Internal bookkeeping columns are held on the table but are hidden from the field list shown to users. Query execution. Widget queries run against the cache table, not against Microsoft Graph. Fields, breakdowns, and filters are applied at query time, results are aggregated per the widget configuration, and a single collapsed row is returned when the widget requests full aggregation.

​

Filters

Widget filters translate into conditions on the cache table using the standard PostgreSQL operator set (postgresFilterOperators) — including equality, comparison, IN, LIKE, and pattern operators. Because the cache table is a flat file snapshot, filters apply to the parsed columns exactly as imported. Date-range filtering applies only when a column has been mapped as the date field during setup. Without a mapped date column, the dashboard date range does not filter the returned rows.

​

Field type mapping

File from OneDrive has no fixed metric or breakdown catalog. The available fields are the columns of the imported CSV, resolved from the cached table after the first successful sync. Because CSV values are untyped on disk, the connector infers each column’s type from its parsed values. Type inference is value-based: a column whose values parse as numbers is exposed as a Number metric; every other column is exposed as Text and can be used as a metric or a breakdown. Date typing is not auto-detected — a column becomes a Date field only when it is mapped as the date field during setup. The following internal cache-bookkeeping columns are always excluded from the available-fields list: id, filename, file_updated_at, created_at, updated_at, and the internal breakdown sentinel column.

​

Adriel-added fields

Beyond the file’s own columns, the file-cache field pipeline exposes helper fields for aggregation.

​

Aggregation defaults

When no explicit aggregation is set on a field, the query builder chooses one based on the inferred type:

​

Limitations

Based on the current connector:

• CSV only. XLSX is not supported for this connector, even though the file-type option exists in code.
• Header row required. The first row of the file must contain column headers; fields are derived from those headers.
• One file per data source. To import multiple files, create multiple data sources.
• Scheduled freshness. Data reflects the most recent successful sync (01:00 / 13:00 UTC), not the live file. Edits made to the file between syncs appear only after the next refresh.
• No connector-level date filtering. The connector honors no date-range parameters (hasDateBreakdown = false); date behavior depends entirely on a date column mapped during setup.
• Row cap per widget query. File-cache queries are capped at 50,000 rows. (Inferred from sibling file connectors; pending tech-review confirmation for this connector.)
• 10-second download timeout. Large CSVs on slow drives may fail to download within the timeout and should be split or relocated.
• Per-call token dependency. A fresh access token is requested before every Graph call from the stored refresh token; revoking the Microsoft OAuth grant breaks all subsequent syncs.
• Auto-disconnect when no file matches. If the file search returns no matching file after pagination, the data source is disconnected (NO_FILE_MATCHING_SETTING) — see the paired how-to for reconnection steps.

​

API references

• Microsoft Graph overview
• OneDrive files API (Microsoft Graph)
• Drive resource type
• Search content with Microsoft Graph
• Download the contents of a driveItem

​

See also

• How to connect File from OneDrive (paired how-to)
• File from SFTP data reference — alternative file source
• File from Email data reference — alternative file source, supports XLSX