Addressing several gaps in documentation from hackathon feedback

docs/cloud/guides/cloud-compatibility.md

@@ -26,22 +26,22 @@ ClickHouse Cloud provides access to a curated set of capabilities in the open so
 
 ### Database and table engines {#database-and-table-engines}
 
-ClickHouse Cloud provides a highly-available, replicated service by default. As a result, all database and table engines are "Replicated". You don't need to specify "Replicated"–for example, `ReplicatedMergeTree` and `MergeTree` are identical when used in ClickHouse Cloud.
-
-**Supported table engines**
-
-- ReplicatedMergeTree (default, when none is specified)
-- ReplicatedSummingMergeTree
-- ReplicatedAggregatingMergeTree
-- ReplicatedReplacingMergeTree
-- ReplicatedCollapsingMergeTree
-- ReplicatedVersionedCollapsingMergeTree
-- MergeTree (converted to ReplicatedMergeTree)
-- SummingMergeTree (converted to ReplicatedSummingMergeTree)
-- AggregatingMergeTree (converted to ReplicatedAggregatingMergeTree)
-- ReplacingMergeTree (converted to ReplicatedReplacingMergeTree)
-- CollapsingMergeTree (converted to ReplicatedCollapsingMergeTree)
-- VersionedCollapsingMergeTree (converted to ReplicatedVersionedCollapsingMergeTree)
+ClickHouse Cloud is a highly-available, replicated service by default, built on the [SharedMergeTree](/cloud/reference/shared-merge-tree) table engine family. When you create a table with a standard MergeTree-family engine, Cloud automatically substitutes the corresponding `Shared*` engine. You don't add a `Shared` or `Replicated` prefix yourself.
+
+| You specify | Cloud uses |
+|---|---|
+| `MergeTree` (or no engine) | `SharedMergeTree` |
+| `ReplacingMergeTree` | `SharedReplacingMergeTree` |
+| `SummingMergeTree` | `SharedSummingMergeTree` |
+| `AggregatingMergeTree` | `SharedAggregatingMergeTree` |
+| `CollapsingMergeTree` | `SharedCollapsingMergeTree` |
+| `VersionedCollapsingMergeTree` | `SharedVersionedCollapsingMergeTree` |
+| `GraphiteMergeTree` | `SharedGraphiteMergeTree` |
+
+`Replicated*` engines are converted to the same `Shared*` equivalents. The substitution is visible in `SHOW CREATE TABLE`, which reports the `Shared*` engine even though your statement specified the plain variant.
+
+The following engines are also supported and used as written:
+
 - URL
 - View
 - MaterializedView

docs/guides/developer/replacing-merge-tree.md

@@ -98,9 +98,11 @@
 
 ## Querying ReplacingMergeTree {#querying-replacingmergetree}
 
-At merge time, the ReplacingMergeTree identifies duplicate rows, using the values of the `ORDER BY` columns as a unique identifier, and either retains only the highest version or removes all duplicates if the latest version indicates a delete. This, however, offers eventual correctness only - it doesn't guarantee rows will be deduplicated, and you shouldn't rely on it. Queries can, therefore, produce incorrect answers due to update and delete rows being considered in queries.
+At merge time, the ReplacingMergeTree identifies duplicate rows, using the values of the `ORDER BY` columns as a unique identifier, and either retains only the highest version or removes all duplicates if the latest version indicates a delete. This, however, offers eventual correctness only - it doesn't guarantee rows will be deduplicated, and you shouldn't rely on it.
 
-To obtain correct answers, you will need to complement background merges with query time deduplication and deletion removal. This can be achieved using the `FINAL` operator.
+:::note[Use FINAL to read deduplicated data]
+Because deduplication only happens during background merges, a plain `SELECT` can still return duplicate or deleted rows. To read correct results at query time, use the `FINAL` modifier, which completes deduplication and deletion removal as the query runs.
+:::
 
 Consider the posts table above. We can use the normal method of loading this dataset but specify a deleted and version column in addition to values 0. For example purposes, we load 10000 rows only.
 

knowledgebase/certificate_verify_failed_error.mdx

@@ -43,6 +43,35 @@ Here is an example configuration:
 </openSSL>
 ```
 
+## Python clients on macOS \{#python-clients-on-macos\}
+
+Python clients report this error differently, typically as:
+
+`ssl.SSLCertVerificationError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate`
+
+On macOS, the Python build from python.org verifies certificates through OpenSSL's default paths rather than the system keychain. On a fresh install, those paths point to no root certificate bundle: the installer ships [certifi](https://pypi.org/project/certifi/) but doesn't link it into OpenSSL's default location until you run the bundled `Install Certificates.command` script. Until then, the client can't validate the ClickHouse Cloud server certificate, even though that certificate is valid. This affects python.org macOS builds generally (Python 3.6 and later), not just Python 3.11.
+
+Run `Install Certificates.command` to link certifi into OpenSSL's default certificate path (adjust the version in the path to match your install):
+
+```bash
+open "/Applications/Python 3.11/Install Certificates.command"
+```
+
+Alternatively, point your client at the certifi bundle directly. [clickhouse-connect](/integrations/python) doesn't fall back to certifi on its own, so pass the bundle through the `ca_cert` parameter:
+
+```python
+import certifi
+import clickhouse_connect
+
+client = clickhouse_connect.get_client(
+    host='HOSTNAME.clickhouse.cloud',
+    port=8443,
+    username='default',
+    password='YOUR_SECRET_PASSWORD',
+    ca_cert=certifi.where(),
+)
+```
+
 ## Additional resources \{#additional-resources\}
 
 View [https://clickhouse.com/docs/interfaces/cli/#configuration_files](https://clickhouse.com/docs/interfaces/cli/#configuration_files)