citusdata / citusdata/citus_docs
Evaluate removing the "create distributed function" section from the quick start guide
- Dominant language
- CSS
- Stars
- 58
- Forks
- 60
- PR merge metrics
- No merged PRs in 30d
Description
## Why are we implementing it? (sales eng)
### What are the typical use cases?
## Communication goals (e.g. detailed howto vs orientation)
Our Quick Start guide is an opportunity to introduce simple concepts to our users.
https://docs.citusdata.com/en/v10.2/get_started/tutorial_multi_tenant.html
In the multi-tenant quick start guide, we introduce the following concept. I feel that the notion of additional roundtrips, creating a new UDF, and then declaring the use of the UDF as a distributed function goes beyond a quick start.
Could we evaluate removing the following section from our Quick Start Guide?
I'm asking because I haven't used create_distributed_function() in this way before. Although I'm not a power user, I also feel that this goes beyond what's needed to get started on Citus.
"Each statement in a transactions causes roundtrips between the coordinator and workers in multi-node Citus. For multi-tenant workloads, it’s more efficient to run transactions in distributed functions. The efficiency gains become more apparent for larger transactions, but we can use the small transaction above as an example.
First create a function that does the deletions:
CREATE OR REPLACE FUNCTION
delete_campaign(company_id int, campaign_id int)
RETURNS void LANGUAGE plpgsql AS $fn$
BEGIN
DELETE FROM campaigns
WHERE id = $2 AND campaigns.company_id = $1;
DELETE FROM ads
WHERE ads.campaign_id = $2 AND ads.company_id = $1;
END;
$fn$;
Next use [create_distributed_function](https://docs.citusdata.com/en/v10.2/develop/api_udf.html#create-distributed-function) to instruct Citus to run the function directly on workers rather than on the coordinator (except on a single-node Citus installation, which runs everything on the coordinator). It will run the function on whatever worker holds the [Shards](https://docs.citusdata.com/en/v10.2/get_started/concepts.html#shards) for tables ads and campaigns corresponding to the value company_id.
SELECT create_distributed_function(
'delete_campaign(int, int)', 'company_id',
colocate_with := 'campaigns'
);
-- you can run the function as usual
SELECT delete_campaign(5, 46);"
### Good locations for content in docs structure
## How does this work? (devs)
### Example sql
### Corner cases, gotchas
### Are there relevant blog posts or outside documentation about the concept/feature?
### Link to relevant commits and regression tests if applicable
Contributor guide
Assessment
This issue has not been assessed yet.