Files and object storage
FACE reads spreadsheets, delimited and JSON files, Parquet, and objects in your own cloud buckets. Every read is streamed and bounded, and a clipped read is always marked as truncated.
Read bounds (all file formats)
| Bound | Default | Meaning |
|---|---|---|
| Bytes read | 64 MiB | A ceiling on what is read from the source, including a single pathological line |
| Rows kept | 10,000 | A ceiling on what is returned |
When either bound is reached, the response message ends with
— TRUNCATED: <reason>.
Supported formats: csv, tsv, json (a top-level array), jsonl / ndjson,
txt, html, parquet, and xlsx / xlsm for Excel. For objects, FACE takes
the format from the key’s extension.
Excel
| Type spellings | excel, xlsx, spreadsheet |
| Config message | ExcelConnectionConfig: file_path, has_header |
| Credentials | None (CREDENTIAL_STATE_NONE_NEEDED) |
| Test | Checks that file_path exists on the reading node, is not a directory, and ends in .xlsx or .xlsm. It is a local file check, not a network dial. |
| Execute | Reads one sheet. The query names the sheet, and an empty query reads the first sheet. Rows are decoded one at a time and stop at the row cap. |
| Explore | supported=false. A workbook’s sheets and header row are its schema. |
For CSV and other delimited text, use an object-store connection or a document source.
Object storage (S3, GCS, Azure Blob)
| Type spellings | objectstore, s3, awss3, gcs, googlecloudstorage, azureblob, azure, blobstorage |
| Config message | ObjectStoreConnectionConfig |
| Setting | Meaning |
|---|---|
provider | s3, gcs or azure. Aliases such as minio, ceph, aws, gcp and azblob are normalised. It is required, and an unknown provider is refused. |
bucket | The bucket, or the container for Azure. Required. |
prefix | An optional key prefix that scopes the connection |
region | S3 region |
endpoint | An S3-compatible endpoint (MinIO, Ceph, your own objectd). Empty means AWS S3 over TLS. For GCS or Azure, a custom service endpoint. |
account | Azure storage account name (required for Azure) |
use_tls | Whether an S3-compatible endpoint given without a scheme uses TLS. A scheme on endpoint overrides it. |
Credential keys:
| Provider | Keys |
|---|---|
| S3 | access_key and secret_key (also aws_access_key_id / aws_secret_access_key), optional session_token |
| GCS | service_account_json (also credentials_json, google_credentials). It may be omitted only with a custom endpoint. |
| Azure | account_key, or sas_token, or connection_string |
- Test has a 10-second budget and runs one live call per provider: S3
BucketExists, GCS bucket attributes, or Azure container properties. Messages distinguish “does not exist, or these credentials cannot see it” from “cannot reach”. - Execute reads one object. The query is the object key, and
prefixis prepended when the key does not already start with it. Parquet objects are read from their footer, and all other formats are streamed. Object reads are implemented for S3-compatible stores. GCS and Azure pass Test, but reading them returnsreading objects is wired for S3-compatible stores only; "…" is not yet supported. - Explore returns
supported=false. Listing a bucket gives keys, not a schema.
Parquet
A Parquet file is read from its footer, so FACE needs its size and random access.
That makes an object in an S3-compatible store the supported source. FACE reads
in batches of 256 rows under the same row cap. A file larger than the byte
ceiling is refused with
parquet file is … bytes, beyond the …-byte ceiling.
Document sources
A fetch hands the following connection types to FACE’s document extraction (OCR) path rather than to a tabular connector:
gdrivegcp_bucketsftplocalpdfwordnetwork
They read connection properties: path (it falls back to the connection name),
host, port, and bucket for buckets. Their output is extracted text.
- SFTP requires a verified host key and refuses to connect without one.
- Downloads stop if nothing arrives for 60 seconds.
- Downloads are capped at 2 GiB by default. The operator setting
FACE_MAX_DOWNLOAD_BYTESchanges the cap.
These types have no registry connector, so Test and Explore do not apply to them.