Add MultiPoint data type

[davidmenggx]

Added the MultiPoint geo data type, stored as Array(Point), and included it in the Geometry type. Geo functions (readWKT/readWKB, wkt, wkb, svg, area, perimeter, polygons*, MVT encoding, GeoJSON input/output, Arrow/Parquet geo metadata) support it.

MySQL integration (the mysql table function/engine and the MySQL database engine) maps the concrete MULTIPOINT column type to MultiPoint, and a generic GEOMETRY column holding a MULTIPOINT value reads back through the Geometry type's MultiPoint alternative (previously both threw or fell back to String; only GEOMETRYCOLLECTION remains unrepresentable).

To keep backward compatibility, Geometry now builds its Variant with a fixed discriminator order (matching the previous sorted-by-name order) and MultiPoint is appended at the end, so discriminators persisted in existing data keep their meaning. This is covered by the test 04511_geometry_discriminators_compatibility, which reads hardcoded Native and RowBinary blobs produced by a pre-MultiPoint server.

Closes: #109852

Changelog category (leave one):

• New Feature

Changelog entry (a user-readable short description of the changes that goes into CHANGELOG.md):

Added the MultiPoint geo data type, stored as Array(Point), and included it in the Geometry type.

Version info

• Merged into: 26.8.1.146 (included in 26.8 and later)

[davidmenggx]

@alexey-milovidov Let me know how this looks, two things:

1. Not implemented yet: WKT/WKB parsing via readWKT/readWKB, the wkt/wkb/svg/area*/perimeter*/polygons* functions, MVT encoding, and GeoJSON input/output. I can implement these in this PR if preferred, or open a follow-up issue to track them.
2. Variant sorts alternatives by name, so adding MultiPoint to Geometry renumbers the discriminators. This causes backward compatibility issues. Maybe we can make the Geometry serialization record the ordered list of variant type names in its serialization prefix and resolve discriminators against that recorded list rather than the current canonical order, the same way Dynamic already persists its variant structure per part?

[alexey-milovidov]

I can implement these in this PR if preferred, or open a follow-up issue to track them.

Let's add all in this PR.

[clickhouse-gh]

Workflow [PR], commit [d31235b]

Summary: ✅

• Performance Comparison: Performance dashboard

---

AI Review

Summary

This PR adds the MultiPoint geo type and threads it through Geometry, WKT/WKB, GeoJSON, GeoParquet, MySQL, MVT, and the geo function set, with the important Geometry discriminator compatibility fix in place. The main feature work is broadly there, but two user-visible behavior gaps still remain in the current code: name-stripping paths still silently reinterpret MultiPoint as Ring, and the updated flipCoordinates docs still promise Geometry type preservation that the implementation does not provide.

Findings

⚠️ Majors

• [src/Functions/geometryConverters.h:533, src/Functions/geometry.h:162] [dismissed by author -- https://github.com/Add MultiPoint data type #109951#discussion_r3622013243, https://github.com/Add MultiPoint data type #109951#discussion_r3622118870] MultiPoint is still only recognized while the custom geo name survives. Once expression analysis strips that name, unnamed Array(Tuple(Float64, Float64)) still falls back to Ring, so generic paths like wkt, svg, polygonConvexHull, h3PolygonToCells*, area*, and perimeter* can silently reinterpret a supported MultiPoint value as an areal ring instead of preserving the geometry kind or rejecting the ambiguous form. This ambiguity predated the PR, but adding MultiPoint turns it into a new wrong-result surface for the feature being added here. Suggested fix: reject the ambiguous unnamed structural form in the shared helpers, analogous to geometryIntersect, or preserve the custom geo name across these dispatch points.
• [src/Functions/flipCoordinates.cpp:161] [dismissed by author -- https://github.com/Add MultiPoint data type #109951#discussion_r3622118876] The updated docs still say flipCoordinates supports Geometry and that "the return type matches the input type", but the implementation still relies on the default FunctionVariantAdaptor path, which returns a plain Variant(...) when the alternatives have different result types. A Geometry input therefore loses the Geometry wrapper and fixed discriminator order, so downstream code that explicitly requires Geometry still rejects the result. This was already true before MultiPoint, but the changed doc line still restates a false contract in the current PR. Suggested fix: preserve the Geometry wrapper explicitly here, or narrow the docs/tests to the concrete geo aliases.

Final Verdict

Status: ⚠️ Request changes

[davidmenggx]

@alexey-milovidov Everything should be implemented now. For backward compatibility MultiPoint is appended to the end of the Geometry variant

[alexey-milovidov]

LGTM. Approved.

[alexey-milovidov]

Pushed fixes for the CI reds of commit bb3d9e1:

• test_mysql_geometry (5 integration jobs): real regression from this PR — parseWKBFormat now parses MULTIPOINT, but the MySQL read path had no MultiPoint branch, so it threw Cannot store a geometry of type into a Geometry column. Fixed in f4b5ef3: MULTIPOINT values in a generic geometry column now read back through the Geometry type's MultiPoint alternative, the concrete multipoint column type maps to MultiPoint, and the test's unrepresentable-subtype regression uses GEOMETRYCOLLECTION instead.
• geometryIntersect{Cartesian,Spherical} (AI review blocker): fixed in 5c2e85c with regression queries for concrete MultiPoint and MultiPoint inside Geometry.
• Docs check (Mintlify): the docs/reference/formats/GeoJSON.mdx update is an intentional regeneration matching the embedded-docs change, so I added the pr-autogenerated-docs label.

Unrelated failures:

• Integration tests (amd_msan, 7/8): test_replicated_database/test.py::test_replicated_table_structure_alter — known flaky, Flaky test: test_replicated_database/test.py::test_replicated_table_structure_alter (regression since 2026-07-10) #110036
• Stress test (arm_msan): Cannot start clickhouse-server due to corrupted txn_version.txt of fabricated parts — Stress tests: Cannot start clickhouse-server — corrupted txn_version.txt of fabricated parts from 04241_part_loading_tree_rollback_* tests #111053, fix in progress in Detach tables permanently in part-loading-tree rollback tests #111055

[alexey-milovidov]

Pushed d880181 fixing the test_mysql_geometry regression from the CI run on f4b5ef3 (5 integration jobs): ExternalResultDescription::init did not classify MultiPoint as vtGeometry, so a concrete MySQL MULTIPOINT column fell through to vtArray and MySQLSource::insertValue threw Unsupported value type. Verified locally against a real MySQL 8 server through the mysql table function.

The remaining two reds on f4b5ef3 are unrelated to this PR:

• 04507_mvt_encode_state_serialize (ParallelReplicas job) — known parallel-replicas Variant conversion bug Cannot convert type UInt8 to Variant(String, UInt64). Parallel replicas variant type conversion #74366, fix in progress: Fix 04507_mvt_encode_state_serialize failure under parallel replicas #111148
• Upgrade check CANNOT_RESTORE_TO_NONENCRYPTED_DISK in 03277_database_backup — benign encrypted Backup-engine restore error, allowlist fix in progress: Allowlist benign encrypted Backup-engine restore error in upgrade check #109042

[groeneai]

@alexey-milovidov this is STID 4752-5ad8, the chronic Input nodes size mismatch in dag LOGICAL_ERROR in the join-order optimizer (a server abort in debug/sanitizer builds only). Unrelated to this PR as you noted: no geometry code in the stack, the path is chooseJoinOrder -> optimizeJoinLogicalImpl -> JoinExpressionActions. It hit 41 distinct PRs over the last 60d, 0 on master.

The fix is already in progress: #110717 (open, under review). It adds a joinGraphHasDuplicateInputNames guard in optimizeJoin.cpp that skips reordering a join step whose DAG carries two INPUT nodes with the same qualified name (the JoinExpressionActions 3-arg constructor requires the input count to equal both sides' column counts at JoinExpressionActions.cpp:124), plus regression test 04517_join_reorder_duplicate_input_correlated_subquery. That guard targets exactly the 4752-5ad8 shape seen here, so a separate PR is not needed.

[alexey-milovidov]

Status update on 5ff95883a4a:

• Addressed both remaining AI-review Nits in 5acd3d76020: the mysql_datatypes_support_level entry in SettingsChangesHistory.cpp and the session-settings.mdx mirror now list MULTIPOINT among the mapped MySQL spatial types (only GEOMETRYCOLLECTION remains unrepresentable), and the flipCoordinates section of other-functions.mdx was regenerated to include MultiPoint.
• Merged master (the branch was 356 commits behind and the stress-test startup failure Cannot start clickhouse-server #111376 is fixed there — the issue is closed). The merge was clean; readWkt.cpp picked up the new POINT EMPTY rejection from master without interaction with the MULTIPOINT parser. Full incremental build passes locally.
• Remaining CI reds on 01b0e292205 were unrelated known flaky tests: test_check_table = Flaky test: test_check_table/test.py::test_check_all_tables #111289, test_replicated_table_structure_alter = Flaky test: test_replicated_database/test.py::test_replicated_table_structure_alter (regression since 2026-07-10) #110036, stress arm_release/arm_debug startup = Cannot start clickhouse-server #111376, and stress arm_tsan was a hung-check timeout under TSan memory pressure ("Cannot drop databases after stress tests" then the 00001_select_1 hung check timed out after 600s) — not related to a geo type change.
• The two Majors about unnamed Array(Point) falling back to Ring and the flipCoordinates Variant return type concern the pre-existing structural ambiguity shared by all geo types and remain a maintainer design decision, as discussed on the threads.

[alexey-milovidov]

CI status on 5ff95883a4a: all four red jobs are unrelated to this PR, so I have restarted the failed jobs on the same run:

• Stateless (amd_asan_ubsan, distributed plan, parallel) — 02477_single_value_data_string_regression: flaky across many unrelated PRs in the last weeks (e.g. Automatically choose between the plain and the secure port in clickhouse-client #110130, Cascades cost-based optimizer for distributed query plans #86353, Fix SIZES_OF_COLUMNS_DOESNT_MATCH in ORDER BY LowCardinality LIMIT after JOIN (#109877) #109897, Reject non-transactional removal of parts created by uncommitted transactions #110494); fixes are in progress in Do not pre-allocate huge buffers when deserializing SingleValueDataString #110630 and Fix flaky 02477_single_value_data_string_regression and 02481_i43247_ubsan_in_minmaxany #110632.
• Stateless (same job) — 04033_tpc_ds_q95: empty query result, marked flaky by CI itself, also seen on unrelated PRs (Support Remote and RemoteSecure storage engines #106189, Store minio audit/server log tables on an explicit local disk, not the default policy #110430, Fix wrong results and MergeTreeSetIndex assertion for reverse sorting key on wide parts #110546, Fix vacuous truth for x op ALL (empty subquery) #106373). @groeneai, investigate the failure: https://s3.amazonaws.com/clickhouse-test-reports/json.html?PR=109951&sha=5ff95883a4a8c6e423ed5e639c3a54e5bf70f006&name_0=PR&name_1=Stateless%20tests%20%28amd_asan_ubsan%2C%20distributed%20plan%2C%20parallel%29 and provide a fix in a separate PR. If the fix is already in progress, link it here.
• Integration (amd_tsan, 3/6) — test_replicated_database/test.py::test_replicated_table_structure_alter: known flaky, Flaky test: test_replicated_database/test.py::test_replicated_table_structure_alter (regression since 2026-07-10) #110036 (retry_ok).
• Stress (arm_asan_ubsan, s3) — Cannot start clickhouse-server while loading test_1.t_plt_rb_contains (corrupted txn_version.txt fabricated by the 04241_part_loading_tree_rollback_* tests): Stress tests: Cannot start clickhouse-server — corrupted txn_version.txt of fabricated parts from 04241_part_loading_tree_rollback_* tests #111053, fix in Detach tables permanently in part-loading-tree rollback tests #111055.

Review state: the three remaining AI-review Majors (geometryConverters.h/geometry.h unnamed-Array(Point) fallback and the flipCoordinates Geometry docs wording) concern the pre-existing structural ambiguity shared by all geo types and are dismissed on their threads as out of scope for this feature PR — they remain a maintainer design decision.

[groeneai]

Acknowledged. Searched open/closed PRs and issues: no in-progress fix for 04033_tpc_ds_q95 exists to link. I will investigate this failure on the amd_asan_ubsan distributed-plan-parallel job and open a separate fix PR, linking it back here (or post my findings here if it turns out not to be actionable in the test itself).

[groeneai]

Investigated 04033_tpc_ds_q95. It is an OOM victim of the shared-server total-memory cap on Stateless tests (amd_asan_ubsan, distributed plan, parallel), not a q95 defect. No separate fix PR: a q95-side change would be a band-aid, and the real controls are already merged and owned here.

Evidence (30d CIDB, test_name='04033_tpc_ds_q95', FAIL/ERROR):

• 6 failures across 5 PRs (the 4 you listed plus this one), all on this one check. head_ref='master': 0.
• Every failure is Code 241 (total) memory limit exceeded, OvercommitTracker "Query was selected to stop". The killed query wanted only 0.7-1.2 GiB while current RSS == maximum (server total already pinned at the cap by co-scheduled queries). Kill site varies run to run (JoiningTransform / FillingRightJoinSide / MergeTreeSelect / ConcurrentHashJoin), which is the victim signature.
• One finished failed run (b899ec444fb8): 1981 Code-241 kills in a single job run, all at the same cap, largest individual killed-query request ~1.01 GiB. No single hog; the RSS is the collective sum of concurrent tests.
• This Add MultiPoint data type #109951 run (5ff95883a4a8): cap is 44.83 GiB (ratio 0.75), and q95 was retried 4+ times (test_cud327hz, test_icnp1x1n, test_k465kmeg, test_ferdvdfz), each attempt killed at 44.83 GiB -> retries exhausted. The runner's own diagnosis then reran it 10x with --no-random-settings -> 10/10 pass in isolation.

q95 is blameless: it already spills GROUP BY and JOIN to disk at 300 MB (max_bytes_before_external_group_by/join) and is tagged no-random-settings/no-flaky-check, so its own footprint is small and stable.

The mitigations for this shard are already merged:

• Lower max_server_memory_usage_to_ram_ratio to 0.7 on sanitizer stateless runs #110293 (ratio 0.7),
• Retry functional tests on server (total) memory limit exceeded #110503 (retry on (total) memory limit exceeded),
• Fix distributed-plan sanitizer OOM: re-apply 0.7 memory ratio + cut concurrency #110574 (this job cut to 0.22*CPU = 7 workers, ratio raised to 0.75).

Per the tuning log now in ci/jobs/functional_tests.py, cutting workers 11 -> 9 -> 8 -> 7 barely moved peak RSS (43.01 -> 41.90 -> 41.76 -> 41.71 GiB): the baseline is dominated by untrackable ASan shadow/quarantine/redzone plus file-backed mmap pages that grow with total work, not concurrency. So concurrency is exhausted as a lever, and the residual is the retained-RSS equilibrium sitting right under the cap; occasionally a query exhausts its retries there.

Conclusion: no q95 PR. The remaining knob is this job's memory ratio vs the host-OOM invariant your functional_tests.py comment already weighs, which is a CI-infra tuning decision. I can open a PR to nudge the distributed-plan-parallel ratio a little higher if you want it; otherwise this is working as designed and I will leave it.

Report: https://s3.amazonaws.com/clickhouse-test-reports/json.html?PR=109951&sha=5ff95883a4a8c6e423ed5e639c3a54e5bf70f006&name_0=PR&name_1=Stateless%20tests%20%28amd_asan_ubsan%2C%20distributed%20plan%2C%20parallel%29

[alexey-milovidov]

Status update: @davidmenggx merged current master into the branch (1c580187a62). The merge itself was fine, but master had just split the autogenerated settings pages (#111434), which deleted docs/reference/settings/formats.mdx and session-settings.mdx in favor of per-group pages generated from master's sources — silently dropping three previously-reviewed doc fixes from this branch. Restored them in d75a41db7bd on the new split pages:

• docs/reference/settings/formats/input-format.mdx: input_format_geojson_unsupported_geometry_handling no longer lists MultiPoint as unrepresentable (matches FormatFactorySettings.h / SettingsChangesHistory.cpp on this branch), and input_format_parquet_allow_geoparquet_parser mentions MultiPoint again.
• docs/reference/settings/session-settings/mysql.mdx: mysql_datatypes_support_level documents the MySQL MULTIPOINT mapping; only GEOMETRYCOLLECTION remains unrepresentable (matches Settings.cpp).

Also: the failed-job rerun on 5ff95883a4a came back fully green (all four earlier reds were confirmed unrelated flakes), and CI is now running on d75a41db7bd.

[alexey-milovidov]

CI status on d75a41db: 152 jobs green; the 3 red jobs are all unrelated to this PR:

• Integration tests (amd_tsan 3/6, amd_msan 7/8) — test_replicated_database/test.py::test_replicated_table_structure_alter, the known flaky Flaky test: test_replicated_database/test.py::test_replicated_table_structure_alter (regression since 2026-07-10) #110036 (both marked retry_ok by the CI itself).
• Upgrade check (amd_release) — two of the three sub-failures are the join_runtime_filter_min_probe_rows settings-history mismatch, fixed on master by Move join_runtime_filter_min_probe_rows settings-history entry from 26.7 to 26.8 #111671; the third is the system.metric_log rotation QUERY_IS_TOO_LARGE error, fix in progress in Do not fail internal system-log ALTER when the metadata exceeds max_query_size #111703.

Merged current master (5ec2b2ed5b6, clean, no conflicts) to pull in #111671 so the settings-history reds clear on the next run; verified the branch's doc and code changes survived master's docs restructure and that an incremental build of clickhouse passes with no warnings. Approved the gated workflow run for the new head.

The AI-review verdict still shows "Request changes", but all three Majors are marked dismissed by author: they concern the pre-existing structural ambiguity of the geo family (MultiPoint/Ring/LineString all being Array(Point) distinguished only by the custom type name) and the shared Variant adaptor — a design decision for the maintainer, out of scope for this feature PR per the earlier approval.

[alexey-milovidov]

Update (head 58b31694ffd):

• Merged master (clean; all 14 documentation edits verified intact after the merge). This pulls in Do not fail internal system-log ALTER when the metadata exceeds max_query_size #111703, which fixes the system.metric_log QUERY_IS_TOO_LARGE error that caused the Upgrade check red on 5ec2b2ed5b6.
• Fixed the remaining live AI-review Major: strAppendGeoValue in BuzzHouse never generated MultiPoint for Geometry values, because it drew from 1..GeoTypes::MultiPolygon while GeoTypes::MultiPoint = 8 sits after GeoTypes::Geometry = 7 in the enumeration. Now a draw of Geometry is remapped to MultiPoint, covering all seven concrete alternatives uniformly.

Remaining reds on 5ec2b2ed5b6 are unrelated to this PR:

• 03216_arrayWithConstant_limits (amd_asan_ubsan, distributed plan): MEMORY_LIMIT_EXCEEDED flake under global memory pressure; fix is Reduce peak memory of test 03216_arrayWithConstant_limits #111705 (open).
• Stress test (arm_asan_ubsan, s3): server child terminated by signal 11 at 16:18:55 with no stack trace, no sanitizer report, and nothing in dmesg. Queries in flight at that moment were unrelated to this PR (01670_sign_function, 03914_has_any_all_tokens_with_tokenizer, 02466_distributed_query_profiler, ...) — no geo/MultiPoint query was running. The same opaque "Unknown error / Lost connection to server" stress failure appears on unrelated PRs (Simplified partition mutations #48941, Add ALTER TABLE ... RECOMPRESS COLUMN #109453) in CIDB. @groeneai, investigate the failure: https://s3.amazonaws.com/clickhouse-test-reports/json.html?PR=109951&sha=5ec2b2ed5b6cf1fc8ede04ce6756bebc1e281cda&name_0=PR&name_1=Stress%20test%20%28arm_asan_ubsan%2C%20s3%29 and provide a fix in a separate PR. If the fix is already in progress, link it here.

The three dismissed threads (geometryConverters.h Ring fallback, geometry.h unnamed-structural mapping, flipCoordinates.cpp docs) remain pre-existing design questions for a maintainer, per the earlier discussion.

[groeneai]

Acknowledged. Confirmed via CIDB this is a chronic cross-PR/trunk crash, not caused by this PR: Stress test (arm_asan_ubsan, s3) FAIL/ERROR hit ~25 unrelated PRs plus 27 master runs in the last 30 days, with #109951 showing the same rate as the rest, so it will not block this PR. I'm pulling the crash core from the 5ec2b2ed5b6 arm_asan_ubsan s3 stress job to get a symbolized backtrace (no CI stack was written for the signal 11), and will follow up here with a separate fix PR or my findings.

[groeneai]

Follow-up: the fix is in #111873.

There was no core to pull: the job never wrote one. The only trace of the crash is the watchdog line <Fatal> Application: Child process was terminated by signal 11. in the server log. Findings from the 111 MB err.log and the CI scripts:

1. The log parser matched only the fault-handler stack (absent here) or the literal signal 9, so a signal-11 death was reported as the opaque "Unknown error".
2. Stress/upgrade jobs can never produce cores: the server starts via sudo, which clamps RLIMIT_CORE to 0/0, so the server's startup raise fails (the recurring "Cannot set max size of core file" warning) and the kernel writes nothing.
3. Even with the limit fixed, core_path=/cores (the only collected mount) was configured only for the late stress-phase restart, so upgrade-job and early-phase crashes would have written cores into a container-local directory that dies with the container.

With no stack, no core, and in-flight queries unrelated to this PR, the SIGSEGV itself cannot be located, and I am not speculating an engine fix without evidence. #111873 fixes all three diagnostics gaps so the next occurrence of this chronic crash (27 master + ~25 unrelated-PR hits in 30 days) carries the signal name and a collectable core dump.

[alexey-milovidov]

CI on 58b3169 completed: 154 passed, one red — Upgrade check (amd_release), unrelated to this PR:

• Error message in clickhouse-server.log: the new server fails to attach test_7.t_plt_reparent at startup with CORRUPTED_DATA (Cannot parse input: expected '\n' before: 'version: 1...'). The table comes from 04063_part_loading_tree_rollback_reparent.sh, which fabricates txn_version.txt files by writing plain text directly into the part's data path. The test is tagged no-object-storage, no-encrypted-storage, but the Upgrade check does not forward those skip tags, so the table landed on cached_s3_encrypted — there the fabricated plain-text file overwrites the local metadata file of the object storage disk, and DiskObjectStorageMetadata::deserialize throws while the upgraded server re-attaches the leaked detached table. The same failure fires across many PRs since 2026-07-23 (84 occurrences). Fix in progress: Upgrade check: honor storage skip tags by forwarding --s3-storage / --encrypted-storage #111772 (@groeneai — this is exactly the failure mode your PR addresses; linking it here).

The AI review verdict flipped to ✅ Approve; the single remaining Nit (QueryFuzzer::getRandomType missing MultiPoint) is fixed in d31235b.

[clickhouse-gh]

LLVM Coverage Report

Metric	Baseline	Current	Δ
Lines	86.20%	86.30%	+0.10%
Functions	92.00%	92.00%	+0.00%
Branches	78.40%	78.40%	+0.00%

Changed lines: Changed C/C++ lines covered: 601/688 (87.35%) · Uncovered code

Full report · Diff report