Merge pull request #260 from oracle-devrel/Ulrike-23c-annotation

Ulrike 23c annotation

Author: JesusGitHubOracle

data-platform/core-converged-db/database-23c/annotations/1-create-table-with-annotations.sql

@@ -0,0 +1,12 @@
+REM  Script for 23c: 1-create-table-with-annotations.sql
+
+-- optional drop table emp_annotated
+drop table if exists emp_annotated; -- with new 23c "if exists" syntax 
+
+-- create a table with two column annotations for ename and salary and a table annotation
+create table emp_annotated
+( empno number,
+  ename varchar2(50) annotations (display 'lastname'),
+  salary number      annotations (person_salary, column_hidden)
+ )
+annotations (display 'employees'); 

data-platform/core-converged-db/database-23c/annotations/2-drop-column-annotation.sql

@@ -0,0 +1,4 @@
+REM  Script for 23c: 2-drop-column-annotation.sql
+
+--- drop a column annotation with ALTER TABLE MODIFY
+alter table emp_annotated modify ename annotations (drop display);

data-platform/core-converged-db/database-23c/annotations/3-create-view-with-annotations.sql

@@ -0,0 +1,13 @@
+REM  Script for 23c: 3-create-view-with-annotations.sql
+
+-- create a view with column annotations for emp_id, emp_name, and emp_dname and an annotation for the view itself
+
+create or replace view empdept_ann
+(emp_id    annotations (identity, display 'employee Id', category 'emp info'),
+ emp_name  annotations (display 'employee name', category 'emp info'),
+ emp_dname annotations (category 'emp info')
+)
+annotations (title 'employee view')
+as select e.empno, e.ename, d.dname 
+from emp e, dept d
+where e.deptno=d.deptno and sal>1000;

data-platform/core-converged-db/database-23c/annotations/4-create-index-with-annotation.sql

@@ -0,0 +1,5 @@
+REM  Script for 23c: 4-create-index-with-annotation.sql
+
+-- create index on column loc with annotation
+
+create index i_loc_dept on dept (loc) annotations (display 'Deptno Location Index');

data-platform/core-converged-db/database-23c/annotations/5-monitor-with-user-annotations-usage.sql

@@ -0,0 +1,17 @@
+REM Script for 23c: 5-monitor-with-user-annotations-usage.sql
+REM Use USER_ANNOTATIONS_USAGE to track the list of annotations and their usage across your schema objects
+
+-- If the annotation is specified for a table column, view column, or domain column, the name of the column, filter on the column name otherwise on NULL
+-- in our case to obtain object-level annotations for table, index, domain and view, we filter on NULL
+
+set lines 200
+set pages 200
+col object_name format a25
+col object_type format a15
+col annotation_name format a15
+col annotation_value format a25
+col column_name format a20
+
+select object_name, object_type, annotation_name, annotation_value 
+from user_annotations_usage
+where column_name is null order by 2,1;

data-platform/core-converged-db/database-23c/annotations/6-monitor-with-user-annotations-usage.sql

@@ -0,0 +1,21 @@
+REM Script for 23c: 6-monitor-with-user-annotations-usage.sql
+REM Use USER_ANNOTATIONS_USAGE to track the list of annotations and their usage across your schema objects
+
+-- Obtain column-level annotations
+
+set lines 200
+set pages 200
+col object_name format a25
+col object_type format a15
+col annotation_name format a15
+col annotation_value format a25
+col column_name format a20
+
+select object_name, object_type, column_name, annotation_name, annotation_value 
+from user_annotations_usage
+where column_name is not null order by 2,1;
+
+-- Display annotations as a single JSON collection per column
+select object_type, object_name, column_Name, JSON_ARRAYAGG(JSON_OBJECT(Annotation_Name, Annotation_Value)) in_jsonformat 
+from user_annotations_usage
+where column_name is not null group by object_type, object_name, column_name;

data-platform/core-converged-db/database-23c/annotations/README.md

@@ -0,0 +1,34 @@
+# annotations
+
+ Annotations (also called application usage annotations) are optional property metadata for database objects. They are centrally stored in the database, so that you can share metadata information across applications, modules, and microservices. You can use them to customize business logic, user interfaces or provide information about your database objects to your metadata repositories.
+ Annotations are supported for the database objectts such as tables and table columns, views and view columns, materialized views and materialized view columns, indexes, and also for domains and multi-column domain columns.
+ An annotation is either a name-value pair or name by itself. The name is mandatory, the value optional and both can be provided as freeform text fields. Annotations can be generated with CREATE or ALTER statements. 
+
+## Useful Links
+
+### Documentation
+
+- [SQL Language Reference 23c](https://docs.oracle.com/en/database/oracle/oracle-database/23/sqlrf/CREATE-TABLE.html#GUID-F9CE0CC3-13AE-4744-A43C-EAC7A71AAAB6)
+- [Database Reference](https://docs.oracle.com/en/database/oracle/oracle-database/23/refrn/ALL_ANNOTATIONS_USAGE.html#GUID-BD09C121-62C2-4881-83AE-99B168095711)
+- [Database Reference](https://docs.oracle.com/en/database/oracle///////oracle-database/23/refrn/USER_ANNOTATIONS.html#GUID-9B38677B-BCC6-45A4-983A-68ABE9661962)
+- [Database Development Guide](https://docs.oracle.com/en/database/oracle/oracle-database/23/adfns/registering-application-data-usage-database.html#GUID-2DAF069E-0938-40AF-B05B-75AFE71D666C)
+
+
+### Team Publications
+
+- [Annotations - The new metadata in 23c](https://blogs.oracle.com/coretec/post/annotations-the-new-metadata-in-23c)
+- [Oracle Database 23c Free Developer Release - 10 features you should know](https://blogs.oracle.com/coretec/post/oracle-database-23c-free-developer-sql)
+
+
+### LiveLabs Workshops
+
+- coming soon
+
+
+# License
+
+Copyright (c) 2023 Oracle and/or its affiliates.
+
+Licensed under the Universal Permissive License (UPL), Version 1.0.
+
+See LICENSE for more details.