DOC-5439 and general cleaning

antora.yml

@@ -5,3 +5,5 @@ start_page: 'index.adoc'
 
 nav:
 - modules/ROOT/nav.adoc
+
+## TODO: Add attributes for DataStax, Astra, Apache Pulsar (Apache Pulsar (TM)/Apache Pulsar/Pulsar), Product (DataStax Apache Pulsar(TM) connector/DataStax Apache Pulsar connector/DataStax Pulsar connector), DSE, Cassandra, etc.

modules/ROOT/nav.adoc

@@ -1,61 +1,29 @@
 .Get started
-* xref:pulsarSizing.adoc[]
 * xref:pulsarInstall.adoc[]
 * xref:pulsarQuickStart.adoc[]
-* https://github.com/datastax/release-notes/blob/master/DataStax_Apache_Pulsar_Connector_1.4_Release_Notes.md[Release notes]
+* xref:cfgRefPulsarDseConnection.adoc[]
+
+.Map topics to tables
+* xref:cfgRefPulsarDseTable.adoc[]
+* xref:cfgPulsarDisplayingTopic.adoc[]
+* xref:cfgPulsarMapKeyPair.adoc[]
+* xref:cfgPulsarMapJson.adoc[]
+* xref:cfgPulsarMapAvroMessages.adoc[]
+* xref:cfgPulsarMapUdt.adoc[]
+* xref:cfgPulsarCqlQuery.adoc[]
+* xref:cfgPulsarMapMultipleTables.adoc[]
+* xref:cfgPulsarMultTopicToTables.adoc[]
 
-.Guides and examples
-* Configuration
-** xref:cfgPulsarConfigTasksMax.adoc[]
-** xref:cfgPulsarColumnWritetimeTimestamp.adoc[]
-** xref:cfgPulsarSettingRowLevelTtl.adoc[]
-** xref:cfgPulsarSettingJavaDriverConfig.adoc[]
-** Mapping Pulsar topics to database tables
-*** xref:cfgPulsarMapTopicTable.adoc[]
-*** xref:cfgPulsarDisplayingTopic.adoc[]
-*** xref:cfgPulsarMapKeyPair.adoc[]
-*** Mapping a message that contains JSON fields
-**** xref:cfgPulsarMapJson.adoc[]
-**** xref:cfgPulsarStringJson.adoc[]
-**** xref:cfgPulsarJsonMessageSchema.adoc[]
-*** xref:cfgPulsarMapAvroMessages.adoc[]
-*** xref:cfgPulsarRecordHeaderToTable.adoc[]
-*** xref:cfgPulsarMapUdt.adoc[]
-*** xref:cfgPulsarMapMultipleTables.adoc[]
-*** xref:cfgPulsarMultTopicToTables.adoc[]
-*** xref:cfgPulsarSelectiveUpdateMapsAndUdts.adoc[]
-*** xref:cfgPulsarCqlQuery.adoc[]
-*** xref:cfgPulsarNowFunction.adoc[]
-* Operations
-** xref:opsPulsarAboutOperations.adoc[]
-** xref:opsPulsarScaling.adoc[]
-** Changing the topic or table schema
-*** xref:opsPulsarChangeSchema.adoc[]
-*** xref:opsPulsarAddField.adoc[]
-*** xref:opsPulsarRemoveField.adoc[]
-*** xref:opsPulsarAddTableColumn.adoc[]
-*** xref:opsPulsarRemoveColumn.adoc[]
-** xref:opsPulsarRestart.adoc[]
-** xref:opsPulsarDisplayConfig.adoc[]
-** xref:opsPulsarUpdateConfig.adoc[]
-** xref:opsPulsarDeleteConnector.adoc[]
-** xref:opsPulsarConnectorStatus.adoc[]
-* Security
-** xref:secPulsarInternalLdapAuth.adoc[]
+.Operations
+* xref:opsPulsarAboutOperations.adoc[]
+* xref:opsPulsarScaling.adoc[]
+* xref:opsPulsarChangeSchema.adoc[]
+* xref:opsPulsarDeleteConnector.adoc[]
 * xref:monPulsarConnectMetrics.adoc[]
-* Troubleshooting
-** xref:trbPulsarTsRecordFailsToWriteToTable.adoc[]
-** xref:trbPulsarTsLargeBatches.adoc[]
-** xref:trbPulsarTsRecordParsingFails.adoc[]
-** xref:trbPulsarTsLoadBalancing.adoc[]
 
-.Reference
-* xref:cfgRefPulsarConnector.adoc[]
-* xref:cfgRefPulsarDseConnection.adoc[]
-* xref:cfgRefPulsarDseTable.adoc[]
-* xref:cfgRefPulsarDates.adoc[]
-* DataStax Enterprise authentication
-** xref:cfgRefPulsarAuth.adoc[]
-** xref:cfgRefPulsarAuthLdap.adoc[]
-* xref:cfgRefPulsarSsl.adoc[]
+.Troubleshooting
+* xref:trbPulsarTsLargeBatches.adoc[]
 * xref:cfgPulsarConfigureErrorHandling.adoc[]
+
+.Release notes
+* https://github.com/datastax/release-notes/blob/master/DataStax_Apache_Pulsar_Connector_1.4_Release_Notes.md[Release notes]

modules/ROOT/pages/cfgPulsarConfigureErrorHandling.adoc

@@ -1,22 +1,30 @@
 = Configure error handling
-:page-tag: pulsar-connector,admin,manage,pulsar
 
-The DataStax Apache Pulsar(TM) Connector provides an optional parameter, `ignoreErrors`.
-When set to `true`, it allows the connector to continue processing records even after an error occurred on the prior record.
+Use the DataStax Apache Pulsar(TM) connector's `ignoreErrors` parameter to specify how the connector handles runtime errors when processing messages from Pulsar topics and writing them to database tables.
 
-[#ignoreErrors]
-ignoreErrors:: Use `ignoreErrors` settings to ignore specific types or all runtime errors, depending on the setting you choose.
+You can configure the connector to ignore specific types of errors or all errors, depending on the option you choose:
+
+`NONE` (default)::
+No errors are ignored.
 +
-|===
-|Value|Meaning|Notes
+Any error causes processing to stop.
 
-|`false`|No errors are ignored|Deprecated - equivalent to `NONE`
-|`true`|Only driver errors are ignored|Deprecated - equivalent to `DRIVER`
-|`NONE`|No errors are ignored; default behavior|
-|`ALL`|All errors are ignored|
-|`DRIVER`|Only driver errors are ignored|
-|===
+`DRIVER`::
+Only driver errors are ignored.
++
+If a driver error occurs, the connector continues processing records.
+Other errors cause processing to stop.
 +
-If you set `ignoreErrors` to any value other than `false`, any erroneous record is logged once and the next record is picked up by the Pulsar Connector automatically.
+Logging of non-blocking driver errors depends on the driver configuration.
+
+`ALL`::
+All errors are ignored.
 +
-Default: `NONE`.
+The connector continues processing records even if an error occurred on the prior record.
+The erroneous record is logged once, and then the next record is picked up by the Pulsar connector automatically.
+
+`false` (deprecated)::
+Use `NONE`.
+
+`true` (deprecated)::
+Use `DRIVER`.

modules/ROOT/pages/cfgPulsarCqlQuery.adoc

@@ -1,45 +1,42 @@
-= Provide CQL queries in mappings
-:page-tag: pulsar-connector,dev,develop,pulsar
+= Use CQL queries in mappings
 
-In the Pulsar topic mapping, you can optionally provide a CQL query that should run when the new record arrives on the Pulsar topic.
+In your connector configuration, you can provide a CQL query to run when a new record arrives on the Pulsar topic.
 
-NOTE: This feature is only meant for advanced use cases. Most often, you can use the standard Pulsar mapping without a query. If you define a query in the topic-to-table mapping, the query has priority and will be used instead of the automatically generated action.
+[IMPORTANT]
+====
+If you define a query in the mapping, the query has priority, and it is used instead of the connector's automatically generated action.
 
-If used, you must provide the bound variables used in the query in the mapping column.
-For example, give the following query:
+This is an advanced feature for specific use cases.
+Typically, you can use the standard Pulsar mapping without a query.
+====
 
-[source,yaml]
-----
-topic:
-  my_topic:
-    my_ks:
-      my_table:
-        query: 'INSERT INTO %s.types (bigintCol, intCol) VALUES (:some_name, :some_name_2)'
-----
+If you set `query`, you must provide the bound variables used in the query in the mapping column.
 
-The corresponding mapping in this example should be defined as:
+In the following example, notice that the bound variables, `:some_name` and `:some_name_2`, are included in the `mapping`:
 
 [source,yaml]
 ----
 topic:
-  my_topic:
-    my_ks:
-      my_table:
+  topic_name:
+    keyspace_name:
+      table_name:
+        query: 'INSERT INTO %s.types (bigintCol, intCol) VALUES (:some_name, :some_name_2)'
         mapping: 'some_name=value.bigint, some_name_2=value.int'
 ----
 
-Additional examples of CQL queries that you could include with the topic-to-table mapping:
+Here are some additional examples of possible CQL queries that you could include in your connector configuration:
 
-[source,cql-language]
+[source,yaml]
 ----
-topic:
-  my_topic:
-    my_ks:
-      my_table:
         query: 'INSERT INTO ks.tbl(pkey,ccol,x) VALUES :pkey, :ccol, :x);'
         query: 'INSERT INTO ks.tbl(pkey,ccol,x) VALUES (:pkey, :ccol, :x) USING TTL :input_ttl'
         query: 'INSERT INTO ks.tbl(pkey,ccol,x) VALUES (:pkey, :ccol, :x) USING TIMESTAMP :input_ts'
         query: 'UPDATE ks.tbl SET somelist = somelist + [:newitem] WHERE pkey = :pkey'
         query: 'DELETE FROM ks.tbl WHERE pkey = :pkey AND ccol = :ccol;'
         query: 'DELETE FROM ks.tbl WHERE pkey = :pkey AND ccol > :ccol1 AND ccol <= :ccol2;'
 ----
+
+[TIP]
+====
+You can use CQL queries in mappings to xref:ROOT:cfgPulsarMapUdt.adoc#selectively-update-maps-and-udts[selectively update UDTs and maps].
+====

modules/ROOT/pages/cfgPulsarDisplayingTopic.adoc

@@ -1,32 +1,26 @@
-= Determining topic data structure
-:page-tag: pulsar-connector,dev,develop,pulsar
+= Determine topic data structure
 
-You can use the Apache Pulsar(TM) `pulsar-client` command line client to examine the structure of Pulsar messages for a topic.
+You can use `https://pulsar.apache.org/docs/en/reference-cli-tools/#consume[pulsar-client]` to examine the structure of Apache Pulsar(TM) messages for a topic.
 
-https://pulsar.apache.org/docs/en/reference-cli-tools/#consume
+This can help you determine your field-to-column mapping.
 
 To show Apache Pulsar messages:
 
-[source,bash]
+[source,bash,subs="+quotes"]
 ----
- bin/pulsar-client consume topic_name -s "subscription_name"
+bin/pulsar-client consume **TOPIC_NAME** -s "**SUBSCRIPTION_NAME**"
 ----
 
-where
+Replace the following:
 
-topic_name:: Name of the Pulsar topic receiving the messages.
+* `**TOPIC_NAME**`: Name of the Pulsar topic receiving the messages.
+* `**SUBSCRIPTION_NAME**`: Arbitrary name for the consumer subscription.
 
-subscription_name:: Arbitrary name for the consumer subscription.
-
-You'll see the message data when a message is received:
+The response is the message data when a message is received.
+For example, the following response indicates a message with a key of `My key` and content of `My content`:
 
 [source,console]
 ----
 ----- got message -----
 key:[My key], properties:[], content:My content
-----
-
-in this case:
-
-* *Key*: My key
-* *Content*: My content
+----