Revise and standardize our UDF naming convention
- Dominant language
- C
- Stars
- 12.8k
- Forks
- 794
- Avg merge
- 2d 14h
- Merged PRs (30d)
- 31
Description
Citus started out with the notion of a single node that served the following purposes in the context of complex analytical workloads. Initially, we named this node the "master node" and other nodes in the cluster as "worker nodes".
In alignment with our earlier naming convention, we also used a simple heuristic for naming our external and internal APIs. If we intended for a function to be run on the "master node", we'd prepend the master_ prefix. If we intended for it to be run on "worker nodes", we'd instead use the worker_ prefix.
Over time, Citus expanded on the set of use cases it addresses, Citus Cloud started managing the nodes in the cluster, and the Citus MX project enabled distributing metadata to all nodes in the cluster. We therefore started referring to this node as the "coordinator node" (#1285).
This issue captures the discussion around our new naming convention. If we're converging on the name "coordinator", we should at a minimum investigate which external function names we should revise / create aliases for.
An initial investigation brings up the following group of UDF names that are external facing.
(1) Citus users rely on the following UDFs as part of their regular flow.
* ``master_add_node``, ``master_remove_node``, ``master_get_active_worker_nodes``: Our users call the add / remove functions as part of their typical Citus setup. Node add/remove functions replace ``pg_worker_list.conf``.
* ``master_modify_multiple_shards``: Our users call the former function to ``UPDATE`` / ``DELETE`` across shards.
* ``master_apply_delete_command``: For hash distributed tables, we can now direct our users to use ``TRUNCATE``. If we do, this function then becomes only applicable for append distributed tables.
(2) Citus users may use the following UDFs as part of their flow.
* ``master_get_table_metadata``: We document this function as a helper function. We also have a similar helper function, ``get_shardid_for_distribution_column`` that doesn't have this prefix.
* ``master_copy_shard_placement``: We refer our users to this function when they need to copy shard placements between machines.
(3) A subset of Citus users rely on the following UDFs or config values as part of their flow.
* ``master_create_empty_shard``, ``master_append_table_to_shard``: Citus users who have append (or range) distributed tables use the following udfs as part of their flow.
* ``binary_master_copy_format`` (GUC): Some Citus users tweak this setting to change the ``COPY`` input / output format between the worker nodes and the coordinator node.
(4) Internal UDFs: We currently have dozens of functions that follow our earlier naming convention. These function definitions are accessible [in this file](https://github.com/citusdata/citus/blob/master/src/backend/distributed/citus.sql).
To standardize our naming for the coordinator node, we should at a minimum revise the names in (1). We also discussed these function names in a different context in #1200. The primary question is whether we should make these naming changes as part of a minor (6.3, etc.) or a major release (7.0).
In either case, we'll likely keep the original functions for backwards compatibility.
Contributor guide
Assessment
This issue has not been assessed yet.