citusdata / citusdata/citus_docs

Evaluate removing the "create distributed function" section from the quick start guide

Open
#1,033 2 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.