Skip to content

Commit d25a92a

Browse files
martin-bach-oraclemartin-bach-oracle
authored
Merge additional examples (#14)
* (23.2.0) annotations * (23.2.0) select without from clause * (23.2.0) returning into enhancements * extended case statement pl/sql * (23.2.0) returning into enhancements clarification
1 parent dfb8074 commit d25a92a

File tree

4 files changed

+624
-0
lines changed

4 files changed

+624
-0
lines changed

‎features/annotations.adoc‎

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
= Annotations
2+
:database-version: 23.2.0
3+
:database-category: sql
4+
5+
[[feature_summary]]
6+
7+
Annotations are a lightweight declarative facility for developers to centrally register usage properties for database schema objects. Annotations are stored in dictionary tables and available to any application looking to standardize behavior across common data in related applications. Annotations are not interpreted by the database in any way and are custom data properties for database metadata - including table columns, tables, and indexes. Applications can use annotations as additional property metadata for rendering user interfaces or customizing application logic.
8+
9+
[source,sql]
10+
[subs="verbatim"]
11+
----
12+
-- example 01: table-level annotation
13+
14+
CREATE TABLE customers (
15+
customer_id INTEGER GENERATED BY DEFAULT ON NULL AS IDENTITY,
16+
email_address VARCHAR2(255 CHAR) NOT NULL,
17+
full_name VARCHAR2(255 CHAR) NOT NULL
18+
)
19+
ANNOTATIONS (
20+
sensitivity 'high',
21+
departments 'sales, delivery',
22+
frontOffice
23+
)
24+
/
25+
26+
-- example 02: adding a column-level annotation
27+
28+
ALTER TABLE customers MODIFY (
29+
email_address ANNOTATIONS ( sensitivity 'highest' )
30+
)
31+
/
32+
33+
-- example 03: table and column level annotations
34+
35+
CREATE TABLE employees
36+
(
37+
id NUMBER(5)
38+
ANNOTATIONS (
39+
identity,
40+
display_as 'Employee ID',
41+
group_name 'Emp_Info'),
42+
name VARCHAR2(50)
43+
ANNOTATIONS (
44+
display_as 'Employee Name',
45+
group_name 'Emp_Info'),
46+
salary NUMBER
47+
ANNOTATIONS (
48+
display_as 'Employee Salary', UI_hidden)
49+
)
50+
ANNOTATIONS (
51+
display_as 'Employee Table'
52+
)
53+
/
54+
55+
-- example 04: query the dictionary for annotation usage
56+
57+
SELECT
58+
object_name,
59+
object_type,
60+
column_name,
61+
annotation_name,
62+
annotation_value
63+
FROM
64+
user_annotations_usage
65+
ORDER BY
66+
object_name,
67+
column_name
68+
/
69+
70+
----
71+
72+
.Result
73+
[source,sql]
74+
[subs="verbatim"]
75+
----
76+
SQL> -- example 01: table-level annotation
77+
SQL> CREATE TABLE customers (
78+
2 customer_id INTEGER GENERATED BY DEFAULT ON NULL AS IDENTITY,
79+
3 email_address VARCHAR2(255 CHAR) NOT NULL,
80+
4 full_name VARCHAR2(255 CHAR) NOT NULL
81+
5 )
82+
6 ANNOTATIONS (
83+
7 sensitivity 'high',
84+
8 departments 'sales, delivery',
85+
9 frontOffice
86+
10 )
87+
11 /
88+
89+
Table CUSTOMERS created.
90+
91+
SQL> -- example 02: adding a column-level annotation
92+
SQL> ALTER TABLE customers MODIFY (
93+
2 email_address ANNOTATIONS ( sensitivity 'highest' )
94+
3 )
95+
4 /
96+
97+
Table CUSTOMERS altered.
98+
99+
SQL> -- example 03: table and column level annotations
100+
SQL> CREATE TABLE employees
101+
2 (
102+
3 id NUMBER(5)
103+
4 ANNOTATIONS (
104+
5 identity,
105+
6 display_as 'Employee ID',
106+
7 group_name 'Emp_Info'),
107+
8 name VARCHAR2(50)
108+
9 ANNOTATIONS (
109+
10 display_as 'Employee Name',
110+
11 group_name 'Emp_Info'),
111+
12 salary NUMBER
112+
13 ANNOTATIONS (
113+
14 display_as 'Employee Salary', UI_hidden)
114+
15 )
115+
16 ANNOTATIONS (
116+
17 display_as 'Employee Table'
117+
18 )
118+
19 /
119+
120+
Table EMPLOYEES created.
121+
122+
SQL> -- example 04: query the dictionary for annotation usage
123+
SQL> SELECT
124+
2 object_name,
125+
4 column_name,
126+
5 annotation_name,
127+
6 annotation_value
128+
7 FROM
129+
8 user_annotations_usage
130+
9 ORDER BY
131+
10 object_name,
132+
11 column_name
133+
12 /
134+
135+
OBJECT_NAME COLUMN_NAME ANNOTATION_NAME ANNOTATION_VALUE
136+
______________ ________________ __________________ ___________________
137+
CUSTOMERS EMAIL_ADDRESS SENSITIVITY highest
138+
CUSTOMERS DEPARTMENTS sales, delivery
139+
CUSTOMERS FRONTOFFICE
140+
CUSTOMERS SENSITIVITY high
141+
EMPLOYEES ID IDENTITY
142+
EMPLOYEES ID GROUP_NAME Emp_Info
143+
EMPLOYEES ID DISPLAY_AS Employee ID
144+
EMPLOYEES NAME DISPLAY_AS Employee Name
145+
EMPLOYEES NAME GROUP_NAME Emp_Info
146+
EMPLOYEES SALARY DISPLAY_AS Employee Salary
147+
EMPLOYEES SALARY UI_HIDDEN
148+
EMPLOYEES DISPLAY_AS Employee Table
149+
150+
12 rows selected.
151+
152+
----
153+
154+
== Benefits
155+
156+
Annotating the data model with metadata provides additional data integrity, consistency and data model documentation benefits. Your applications can store user-defined metadata for database objects and table columns that other applications or users can retrieve and use. Storing the metadata along with the data guarantees consistency and universal accessibility to any user or application that uses the data.
157+
158+
== Further information
159+
160+
* Availability: All Offerings
161+
* https://docs.oracle.com/en/database/oracle/oracle-database/23/cncpt/application-data-usage.html#GUID-D5D5615C-BB2C-4833-A9AF-6BAF0BF9CEC0[Database Concepts Guide]
162+
* https://docs.oracle.com/en/database/oracle/oracle-database/23/adfns/registering-application-data-usage-database.html#GUID-2DAF069E-0938-40AF-B05B-75AFE71D666C[Database Development Guide]

‎features/extended-case-controls.adoc‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
= Extended CASE Controls
2+
:database-version: 23.2.0
3+
:database-category: plsql
4+
5+
[[feature_summary]]
6+
7+
The `CASE` statement is extended in *PL/SQL* to be consistent with the updated definitions of `CASE` expressions and `CASE` statements in the `SQL:2003 Standard [ISO03a, ISO03b]`.
8+
9+
At the time of writing there is no SQL equivalent of the extended PL/SQL `CASE` statement.
10+
11+
[source,sql]
12+
[subs="verbatim"]
13+
----
14+
begin
15+
-- example 01: assign grades to result percentages
16+
for inx in -1, 19, 50, 75, 99, null loop
17+
dbms_output.put_line (
18+
nvl ( to_char ( inx ), 'null' ) || ' = ' ||
19+
case inx
20+
when < 0, > 100 then 'invalid result'
21+
when is null then 'no result'
22+
when between 90 and 100 then 'A'
23+
when >= 80 then 'B'
24+
when >= 70 then 'C'
25+
when >= 60 then 'D'
26+
when >= 50 then 'E'
27+
else 'fail'
28+
end
29+
);
30+
end loop;
31+
end;
32+
/
33+
----
34+
35+
.Result
36+
[source,sql]
37+
[subs="verbatim"]
38+
----
39+
SQL> begin
40+
2 -- example 01: assign grades to result percentages
41+
3 for inx in -1, 19, 50, 75, 99, null loop
42+
4 dbms_output.put_line (
43+
5 nvl ( to_char ( inx ), 'null' ) || ' = ' ||
44+
6 case inx
45+
7 when < 0, > 100 then 'invalid result'
46+
8 when is null then 'no result'
47+
9 when between 90 and 100 then 'A'
48+
10 when >= 80 then 'B'
49+
11 when >= 70 then 'C'
50+
12 when >= 60 then 'D'
51+
13 when >= 50 then 'E'
52+
14 else 'fail'
53+
15 end
54+
16 );
55+
17 end loop;
56+
18 end;
57+
19 /
58+
-1 = invalid result
59+
19 = fail
60+
50 = E
61+
75 = C
62+
99 = A
63+
null = no result
64+
65+
PL/SQL procedure successfully completed.
66+
----
67+
68+
== Benefits
69+
70+
Dangling predicates allow tests other than equality to be performed in simple `CASE` operations. Multiple choices in `WHEN` clauses allow `CASE` operations in *PL/SQL* to be written with less duplicated code.
71+
72+
== Further information
73+
74+
* Availability: All Offerings
75+
* https://docs.oracle.com/en/database/oracle/oracle-database/23/lnpls/CASE-statement.html#GUID-F4251A23-0284-4990-A156-00A92F83BC35[Database PL/SQL Language Reference]

0 commit comments

Comments
 (0)