cockroachdb / cockroachdb/cockroach

sql/importer: document parquet IMPORT behaviors found during 26.3 QA

Open
#172,344 0 comments 0 reactions 0 assignees View on GitHub
A-docs A-import C-enhancement O-agent O-qa T-sql-foundations
Dominant language
Go
Stars
32.5k
Forks
4.1k
PR merge metrics
PR metrics pending

Description

**Describe the problem**

Behaviors observed during 26.3 parquet IMPORT QA that are working as designed (or acceptably) but will surprise users — worth explicit documentation on the IMPORT INTO / parquet pages:

1. **`http://` sources require Range-request support.** Parquet needs seekable access, so the HTTP reader issues ranged reads. A plain `python -m http.server` fails (with a decent error: `http server does not honor download resume`) even though it works for CSV.
2. **Triggers do not fire during IMPORT.** A `BEFORE INSERT` row trigger that fires on normal INSERT stays silent for imported rows (expected for bulk ingestion; currently undocumented).
3. **FK and CHECK constraints are downgraded to NOT VALID by IMPORT INTO** — violating rows import successfully (`pg_constraint.convalidated = f`; same as CSV). Users should run `VALIDATE CONSTRAINT` afterwards.
4. **URI glob gotchas:** `?` in a URI is a query-string separator, so `t?.parquet` is read as path `t` with parameters — use `[N]`/`*` instead.
5. **Timestamp semantics:** TIME/TIMESTAMP NANOS values are *truncated* (not rounded) to microsecond precision; `isAdjustedToUTC` is ignored — naive parquet timestamps imported into TIMESTAMPTZ are silently interpreted as UTC.
6. **Computed columns:** a file column matching a STORED computed column is silently ignored (value computed instead), even under `strict_validation` — differs from CSV, which errors on explicitly targeted computed columns.

**Expected behavior**

Each of the above stated in the IMPORT parquet docs.

**Environment:**

- Observed on current master (26.3 dev) during feature QA.

Jira issue: CRDB-65571

Epic CRDB-66113

Contributor guide

Open the contributing guide

Research direction

Start with the IMPORT INTO and parquet documentation pages named in the issue, and compare their current coverage with the six behaviors observed during 26.3 QA. Done means each behavior—Range requests, triggers, constraint validation, URI globs, timestamp handling, and computed columns—is explicitly documented with the relevant user-facing guidance.

Written by the indexing model from the issue text.

Assessment

Tech stack
sql
Domain
databases, documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.