Postgres Type Attribute Nullability Documentation

postgraphile/website/versioned_docs/version-4/custom-queries.md

@@ -46,6 +46,15 @@ could be queried in GraphQL like this:
 }
 ```
 
+:::tip Nullability Note
+
+By default all attributes on postgres types are nullable, and so a function that
+returns a type instead of a table will have all its fields treated as such by the
+generated GraphQL schema. This can be over-ridden on an attribute-by-attribute basis
+with the `@notNull` [smart tag](./smart-tags).
+
+:::
+
 ### Example
 
 Here we write a search query for our [forum example][] using the PostgreSQL
@@ -83,6 +92,25 @@ create function search_posts(search text)
   $$ language sql stable;
 ```
 
+Or using a type to return the exact shape of data you need:
+
+```sql {5}
+create type post_search_result as (
+  headline         text,
+  body             text
+);
+comment on column post_search_result.headline is E'@notNull';
+
+create function search_posts(search text)
+  returns setof post_search_result as $$
+    select headline, body
+    from post
+    where
+      headline ilike ('%' || search || '%') or
+      body ilike ('%' || search || '%')
+  $$ language sql stable;
+```
+
 And that’s it! You can now use this function in your GraphQL like so:
 
 ```graphql {2}

postgraphile/website/versioned_docs/version-4/smart-tags.md

@@ -71,7 +71,8 @@ The column can also be renamed:
 comment on column original_table.col1 is E'@name colA';
 ```
 
-The same can be done for types and custom queries:
+The same can be done for types, type attributes (i.e. "columns"), and custom
+queries:
 
 ```sql
 create type flibble as (f text);
@@ -81,6 +82,7 @@ create function getFlamble() returns SETOF flibble as $$
 $$ language sql;
 
 comment on type flibble is E'@name flamble';
+comment on column flibble.f is E'@notNull';
 comment on function getFlamble() is E'@name allFlambles';
 ```