[Docs RFC] Experimenting with the page: /api/latest/hyperfunctions/days_in_month/

[clarkbw]

Describe change in content, appearance, or functionality

I'd like to experiment with a different docs format for hyperfunctions in Toolkit. I'm basing a lot of this off what MDN is and has done in the past.

Here's what the format looks like:

What it does

One or two sentence description of what this function does and should be used for

Examples

Unless part of a tutorial these need to be inline examples that can run on their own using subqueries or generate_series Also these should be useful solution examples: Here's how you query X to find Y The syntax section below is for straight up "run the function" examples ex:

SELECT revenue / toolkit_experimental.days_in_month(month) as daily_rev FROM (SELECT 100 as revenue, '2021-01-01'::date as month) rev;
...

Syntax

Code examples of the various ways you can call this function

SELECT toolkit_experimental.days_in_month(now()::timestamptz) -- 31
...

Parameters

Function arguments and their definitions

Return value

Any value returned from the function and its format

Exceptions

Errors handled or unhandled by this function

Polyfill

The core code that runs this function and could be used without the extension at all This is a critical part of the page to provide value to those who aren't or can't use Timescale

CREATE FUNCTION …

---

For example:

What it does

Get the number of days in a month for PostgreSQL. This function returns the exact number of days in any month based on a given a date or timestamp.

Examples

-- coming soon

Syntax

SELECT toolkit_experimental.days_in_month('2021-01-01 00:00:00+03'::timestamptz) -- 31
SELECT toolkit_experimental.days_in_month('2021-02-01 00:00:00+03'::timestamptz) -- 28
SELECT toolkit_experimental.days_in_month('2021-01-01'::date) -- 31
SELECT toolkit_experimental.days_in_month('2021-02-01'::date) -- 28
SELECT toolkit_experimental.days_in_month('2021-01-01') -- 31
SELECT toolkit_experimental.days_in_month('2021-02-01') -- 28

SELECT toolkit_experimental.days_in_month('2020-02-01') -- 29

-- works with functions as well
SELECT toolkit_experimental.days_in_month(now()::timestamptz)
SELECT toolkit_experimental.days_in_month(now()::date)
SELECT toolkit_experimental.days_in_month(now())

Parameters

Name	Type	Description
date	TIMESTAMPTZ	Timestamp of the month to retrieve the number of days from

Return value

Returns an integer value for the number of days

Exceptions

Non-date like parameters will return an error. For example passing an integer 2 or non-date string 'yolo' will result in an error.

Polyfill

With this polyfill you would call SELECT days_in_month(now()) without the toolkit_experimental.days_in_month.

CREATE FUNCTION days_in_month(date timestamptz) RETURNS int AS $$ 
SELECT CAST(EXTRACT('day' FROM ($1 + interval '1 month' - $1)) as INTEGER) 
$$ LANGUAGE SQL STRICT IMMUTABLE PARALLEL SAFE; 

Subject matter expert (SME)

I'll be pulling people in as needed to assist with examples.

Deadline

Not urgent, I'll be working iteratively on this change over the next few weeks.

Any further info

I know this is a change from the existing formats and I am only interested in experimenting with this and maybe 1 other page in this new format. We can revert this page back to the original page if we feel this format doesn't work or the experiment doesn't produce the results we're expecting. I'd like to run this experiment for about 1 quarter.

[jamessewell]

@clarkbw are you still running this experiment?