Add base datatype API doc and examples. #220

lyupan · 2023-07-21T00:13:02Z

Description of changes:
Add data type API doc and examples

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

formalLogicGirl · 2023-07-21T16:40:33Z

docs/09_datatypes.md

@@ -0,0 +1,384 @@
+# Trusted Language Base types
+
+PostgreSQL provides `CREATE TYPE` command to register a new base type (scalar type) for use in the current database. Base type allows you to customized how the data is stored interally and how to converts it from/to an external textual representation. The support functions `input_function` and `output_function` are required. The `input_function` converts the type's external textual representation to the internal representation. `output_function` performs the reverse transformation. Generally they have to be coded in C or another low-level language. Also, you must be a superuser to create a new base type.


Base type allows you to customized --> A base type allows you to customize

spelling : internally

how to converts --> how to convert

formalLogicGirl · 2023-07-21T16:42:43Z

docs/09_datatypes.md

+
+### `pgtle.create_shell_type(typenamespace regnamespace, typename name)`
+
+`create_shell_type` provides a way to create a shell type, which is simply a placeholder for a type to be defined later. This is similar to shell type form of `CREATE TYPE`.


should we embed a link here to Postgres docs for shell type

formalLogicGirl · 2023-07-21T16:44:07Z

docs/09_datatypes.md

+
+### `pgtle.create_base_type(typenamespace regnamespace, typename name, infunc regprocedure, outfunc regprocedure, internallength int4)`
+
+`create_base_type` provides a way to create a new base data type. The type must be a shell type previously defined by `create_shell_type`. This is similar to base type form of `CREATE TYPE` command. Internally, a base data type created by `pg_tle` is stored as `bytea`, it can be casted to `bytea` explicitly after creation.


casted --> cast

formalLogicGirl · 2023-07-21T16:46:21Z

docs/09_datatypes.md

+
+* `typenamespace`: The namespace where the base data type will be created.
+* `typename`: The name of the base data type.
+* `infunc`: The name of a previously defined function to converts the type's external textual representation to the internal representation (`bytea`). The function must be declared as taking one argument of type `text` and returning `bytea`. The function must also be declared `IMMUTABLE` and `STRICT`. It will not be called with a NULL parameter.


previously defined function to coverts --> previously defined function to covert

The function must take one argument...and return bytea.

formalLogicGirl · 2023-07-21T16:47:09Z

docs/09_datatypes.md

+* `typenamespace`: The namespace where the base data type will be created.
+* `typename`: The name of the base data type.
+* `infunc`: The name of a previously defined function to converts the type's external textual representation to the internal representation (`bytea`). The function must be declared as taking one argument of type `text` and returning `bytea`. The function must also be declared `IMMUTABLE` and `STRICT`. It will not be called with a NULL parameter.
+* `outfunc`: The name of a previously defined function to converts the type's internal binary representation (`bytea`) to the external textual representation. The function must be declared as taking one argument of type `bytea` and returning `text`. The function must also be declared `IMMUTABLE` and `STRICT`. It will not be called with a NULL parameter.


same comments as for infunc

formalLogicGirl · 2023-07-21T17:40:14Z

docs/09_datatypes.md

+
+```sql
+SELECT pgtle.create_base_type('public', 'test_citext', 'test_citext_in(text)'::regprocedure, 'test_citext_out(bytea)'::regprocedure, -1);
+```


Can we include a fixed-length example as well?

formalLogicGirl · 2023-07-21T17:51:30Z

docs/09_datatypes.md

+
+* `typenamespace`: The namespace where the new operator function will be created. It must be the same namespace where the base data type is.
+* `typename`: The name of the base data type.
+* `opfunc`: The name of a previously defined operator function. The function must be declared as taking one or two arguments of type `bytea`.


must take exactly one or two ...

formalLogicGirl · 2023-07-21T17:52:46Z

docs/09_datatypes.md

+```
+
+## Examples
+The following examples demonstrates how to use `pg_tle` data type APIs functions to create a base data type. After running this example, a base data type called `test_citext` (case-insentive text) will be available for use in the current database.


demonstrates -> demonstrate
APIs -> API

formalLogicGirl · 2023-07-21T17:55:51Z

docs/09_datatypes.md

+The following examples demonstrates how to use `pg_tle` data type APIs functions to create a base data type. After running this example, a base data type called `test_citext` (case-insentive text) will be available for use in the current database.
+
+### Create shell type
+First, you will need to use `pgtle.create_shell_type` to create a shell type in the target namespace (PUBLIC in our example).


I'd drop 'you' from the docs. Maybe 'we'. Or rephrase as
First, pgtle.create_shell_type is called to create a shell type in the target namespace (PUBLIC in this example)

I'll drop most you from the docs, and use either an imperative sentence or we.

formalLogicGirl · 2023-07-21T17:56:20Z

docs/09_datatypes.md

+```
+
+### Create I/O functions
+Second, you will need to define the input/output function on the data type. Remember the input function takes one argument of type `text` and returns `bytea`; while the output function takes one argument of type `bytea` and returns `text`.


similar comment to above

formalLogicGirl · 2023-07-21T17:58:20Z

docs/09_datatypes.md

+INSERT INTO test_dt VALUES ('SELECT'), ('INSERT'), ('UPDATE'), ('DELETE');
+INSERT INTO test_dt VALUES ('select');
+```
+`'SELECT'` and `'select'` is considered different values at this moment because we haven't defined related operators and operator class for the type.


formalLogicGirl · 2023-07-21T17:59:33Z

docs/09_datatypes.md

+`'SELECT'` and `'select'` is considered different values at this moment because we haven't defined related operators and operator class for the type.
+
+### Create operator functions
+After the base data type is created, you can define operators and operator class if needed.


similar as comments before. "... can be defined"

formalLogicGirl · 2023-07-21T18:00:53Z

docs/09_datatypes.md

+```
+
+### Alternative way to operator functions
+Alternatively, you can use `pgtle.create_operator_func` to create operator functions without explicit cast. It can be really helpful in certains languages such as plrust where the newly created type is not available.


can be used

formalLogicGirl · 2023-07-21T18:02:33Z

docs/09_datatypes.md

+);
+```
+
+Run following command to create operator class. Note you need superuser permission here. If you are using Amazon RDS, superuser permission is not required.


superuser permission is required...

formalLogicGirl · 2023-07-21T18:06:33Z

docs/09_datatypes.md

+```
+
+## Examples
+The following examples demonstrates how to use `pg_tle` data type APIs functions to create a base data type. After running this example, a base data type called `test_citext` (case-insentive text) will be available for use in the current database.


Since the example is fairly long, I'm thinking that it helps to have a sql file for the example in addition to the step by step walkthrough in the doc. We don't have an examples directory, which me might want to add now. Or we may have some other place outside of this repo for examples, but I'm not sure where and that could be set up in the future.

Good idea! We already have a few example files, each example file corresponds to one language. I'm thinking if we should add the data type examples to the existing ones or create separate one for data type.

I think an example in a single language in the docs is enough for now -- we can/should revisit adding examples in other languages and pulling out the examples into .sql files

Makes sense. I've added the datatype examples in plpgsql example file. I guess we can revisit/re-structure the example files later.

Add base datatype API doc and examples.

18ce5b4

formalLogicGirl reviewed Jul 21, 2023

View reviewed changes

Minor updates to datatype doc

9360ca1

formalLogicGirl reviewed Jul 21, 2023

View reviewed changes

Lyu Pan added 4 commits July 21, 2023 19:06

Minor updates to datatype doc

6ea5cbf

Minor update is->are

a382ce4

Add datatype examples in plpgsql examples doc.

109e888

Fix minor typos

edb66a4

adamguo0 approved these changes Jul 24, 2023

View reviewed changes

formalLogicGirl approved these changes Jul 24, 2023

View reviewed changes

formalLogicGirl merged commit 7c06d9c into aws:main Jul 24, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add base datatype API doc and examples. #220

Add base datatype API doc and examples. #220

lyupan commented Jul 21, 2023

formalLogicGirl Jul 21, 2023

lyupan Jul 21, 2023

formalLogicGirl Jul 21, 2023

lyupan Jul 21, 2023

formalLogicGirl Jul 21, 2023

lyupan Jul 21, 2023

formalLogicGirl Jul 21, 2023

lyupan Jul 21, 2023

formalLogicGirl Jul 21, 2023

lyupan Jul 21, 2023

formalLogicGirl Jul 21, 2023

lyupan Jul 21, 2023

formalLogicGirl Jul 21, 2023 •

edited

Loading

lyupan Jul 21, 2023

formalLogicGirl Jul 21, 2023

lyupan Jul 21, 2023

formalLogicGirl Jul 21, 2023

lyupan Jul 21, 2023

formalLogicGirl Jul 21, 2023

lyupan Jul 21, 2023

formalLogicGirl Jul 21, 2023

lyupan Jul 21, 2023

formalLogicGirl Jul 21, 2023

lyupan Jul 21, 2023

formalLogicGirl Jul 21, 2023

lyupan Jul 21, 2023

formalLogicGirl Jul 21, 2023

lyupan Jul 21, 2023

formalLogicGirl Jul 21, 2023

lyupan Jul 21, 2023

adamguo0 Jul 24, 2023

lyupan Jul 24, 2023

		@@ -0,0 +1,384 @@
		# Trusted Language Base types

		PostgreSQL provides `CREATE TYPE` command to register a new base type (scalar type) for use in the current database. Base type allows you to customized how the data is stored interally and how to converts it from/to an external textual representation. The support functions `input_function` and `output_function` are required. The `input_function` converts the type's external textual representation to the internal representation. `output_function` performs the reverse transformation. Generally they have to be coded in C or another low-level language. Also, you must be a superuser to create a new base type.


		### `pgtle.create_shell_type(typenamespace regnamespace, typename name)`

		`create_shell_type` provides a way to create a shell type, which is simply a placeholder for a type to be defined later. This is similar to shell type form of `CREATE TYPE`.


		### `pgtle.create_base_type(typenamespace regnamespace, typename name, infunc regprocedure, outfunc regprocedure, internallength int4)`

		`create_base_type` provides a way to create a new base data type. The type must be a shell type previously defined by `create_shell_type`. This is similar to base type form of `CREATE TYPE` command. Internally, a base data type created by `pg_tle` is stored as `bytea`, it can be casted to `bytea` explicitly after creation.

Add base datatype API doc and examples. #220

Add base datatype API doc and examples. #220

Conversation

lyupan commented Jul 21, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

formalLogicGirl Jul 21, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

formalLogicGirl Jul 21, 2023 •

edited

Loading