Using Collections

Overview of Collections
A collection is an ordered group of elements, all of the same
type
Each element has a unique subscript that determines its
position in the collection
Although collections can have only one dimension, you can
model multi-dimensional arrays by creating collections whose
elements are also collections
To use collections in an application, you define one or more
PL/SQL types, then define variables of those types
Collection Types
PL/SQL offers these collection types:
Index-by tables, also known as associative arrays, let you look
up elements using arbitrary numbers and strings for subscript
values

Nested tables hold an arbitrary number of elements. They use

sequential numbers as subscripts

Varrays (short for variable-size arrays) hold a fixed number of

elements (although you can change the number of elements at
runtime). They use sequential numbers as subscripts
Understanding Nested Tables

Nested tables can be considered one-column database

tables
Oracle stores the rows of a nested table in no particular
order. But, when you retrieve the nested table into a
PL/SQL variable, the rows are given consecutive
subscripts starting at 1
PL/SQL nested tables are like one-dimensional arrays
You can model multi-dimensional arrays by creating
nested tables whose elements are also nested tables
Understanding Nested Tables......
Nested tables differ from arrays in two important ways:
1. Arrays have a fixed upper bound, but nested tables are
unbounded

2. Arrays must be dense (have consecutive subscripts). Initially,

nested tables are dense, but they can become sparse (have
nonconsecutive subscripts). So, you can delete elements from a
nested table
Understanding Varrays
Items of type VARRAY are called varrays
They allow you to associate a single identifier with an entire
collection
You can manipulate the collection as a whole and reference
individual elements easily

current upper bound for varray Grades is 7

A varray has a maximum size, which you must specify in

its type definition
Understanding Associative
Arrays (Index-By Tables)
Associative arrays are sets of key-value pairs, where each key is
unique and is used to locate a corresponding value in the array

The key can be an integer or a string

It is like a simple version of a SQL table where you can retrieve

values based on the primary key

Associative arrays are intended for temporary data rather than

storing persistent data, you cannot use them with SQL
statements such as INSERT and SELECT INTO
 Associative Arrays Example....
DECLARE
TYPE population_type IS TABLE OF NUMBER INDEX BY VARCHAR2(64);
country_population population_type;
howmany NUMBER;
which VARCHAR2(64);
BEGIN
country_population('Greenland') := 100000;
country_population('Iceland') := 750000;-- Creates new entry
country_population('Iceland') := 60000; -- Replaces previous value
howmany := country_population('Greenland');
DBMS_OUTPUT.PUT_LINE('Population Of Greenland is - '||howmany);
which := country_population.LAST; -- Returns 'Iceland' Alphabetically
DBMS_OUTPUT.PUT_LINE('Last key is - '||which);
howmany := country_population(country_population.LAST);
DBMS_OUTPUT.PUT_LINE('Population Of '||which||' is - '||howmany);
END;
Choosing PL/SQL Collection Types to Use

Choosing Between Nested Tables and Associative Arrays

Nested tables can be stored in a database column, but associative arrays

cannot. Nested tables are appropriate for important data relationships that
must be stored persistently
Associative arrays are appropriate for relatively small lookup tables where
the collection can be constructed in memory each time a procedure is called
or a package is initialized
Associative arrays index values are more flexible, because associative array
subscripts can be negative, can be nonsequential, and can use string values
instead of numbers when appropriate
PL/SQL automatically converts between host arrays and associative arrays
that use numeric key values
Choosing PL/SQL Collection Types to Use

Choosing Between Nested Tables and Varrays

Varrays are a good choice when the number of elements is known in

advance, and when the elements are usually all accessed in sequence. When
stored in the database, varrays retain their ordering and subscripts.
You must update or retrieve all elements of the varray at the same time,
which is most appropriate when performing some operation on all the
elements at once. But you might find it impractical to store and retrieve large
numbers of elements this way..
Nested tables can be sparse: you can delete arbitrary elements, rather than
just removing an item from the end. This makes nested tables suitable for
queries and updates that only affect some elements of the collection.
Defining Collection Types
For nested tables, use the syntax:
TYPE type_name IS TABLE OF element_type [NOT NULL];
type_name is a type specifier used later to declare collections. element_type is any
PL/SQL datatype except: REF CURSOR
For varrays, use the syntax:
TYPE type_name IS {VARRAY | VARYING ARRAY} (size_limit)
OF element_type [NOT NULL];
Ex. TYPE Calendar IS VARRAY(366) OF DATE;
For associative arrays (index-by tables), use the syntax:
TYPE type_name IS TABLE OF element_type [NOT NULL]
INDEX BY [BINARY_INTEGER | PLS_INTEGER | VARCHAR2(size_limit)];
Ex. DECLARE
TYPE EmpTabTyp IS TABLE OF emp%ROWTYPE INDEX BY BINARY_INTEGER;
emp_tab EmpTabTyp;
BEGIN
SELECT * INTO emp_tab(7468) FROM emp WHERE empno = 7468; -- Retrieve
employee record.
END;
Defining SQL Types Equivalent to
PL/SQL Collection Types
Nested Table Example
The following SQL*Plus script shows how you might declare a nested table in
SQL, and use it as an attribute of an object type:
CREATE TYPE CourseList AS TABLE OF VARCHAR2(10) -- define type
/
CREATE TYPE Student AS OBJECT ( -- create object
id_num INTEGER(4),
name VARCHAR2(25),
address VARCHAR2(35),
status CHAR(2),
courses CourseList) -- declare nested table as attribute
/
The identifier courses represents an entire nested table. Each element of
courses will store the code name of a college course such as 'Math
1020'
Defining SQL Types Equivalent to
PL/SQL Collection Types
Varray Example
The script below creates a database column that stores varrays. Each varray element
contains a VARCHAR2.
-- Each project has a 16-character code name.
-- We will store up to 50 projects at a time in a database column.
CREATE TYPE ProjectList AS VARRAY(50) OF VARCHAR2(16);
/
CREATE TABLE department ( -- create database table
dept_id NUMBER(2),
name VARCHAR2(15),
budget NUMBER(11,2),
-- Each department can have up to 50 projects.
projects ProjectList)
/
Declaring PL/SQL Collection
Variables
Once you define a collection type, you can declare variables of that type.
Example: Declaring Nested Tables, Varrays, and Associative Arrays

DECLARE
TYPE nested_type IS TABLE OF VARCHAR2(20);
TYPE varray_type IS VARRAY(50) OF INTEGER;
TYPE associative_array_type IS TABLE OF NUMBER
INDEXED BY BINARY_INTEGER;
v1 nested_type;
v2 varray_type;
v3 associative_array_type;
p1 v2%TYPE; -- %TYPE declaration
Declaring PL/SQL Collection
Variables
Example: Declaring a Procedure Parameter as a Nested Table
CREATE PACKAGE personnel AS
TYPE Staff IS TABLE OF Employee;
...
PROCEDURE award_bonuses (members IN Staff);
END personnel;
To call PERSONNEL.AWARD_BONUSES from outside the package,
you declare a variable of type PERSONNEL.STAFF and pass that
variable as the parameter.
You can also specify a collection type in the RETURN clause of a
function specification:
DECLARE
TYPE SalesForce IS VARRAY(25) OF Salesperson;
FUNCTION top_performers (n INTEGER) RETURN SalesForce IS .....
Declaring PL/SQL Collection
Variables
Example: Specifying Collection Element Types with %TYPE and %ROWTYPE
DECLARE
TYPE EmpList IS TABLE OF emp.ename%TYPE; -- based on column
CURSOR c1 IS SELECT * FROM dept;
TYPE DeptFile IS VARRAY(20) OF c1%ROWTYPE; -- based on cursor
Example: VARRAY of Records
DECLARE
TYPE AnEntry IS RECORD (
term VARCHAR2(20),
meaning VARCHAR2(200));
TYPE Glossary IS VARRAY(250) OF AnEntry;
Example: NOT NULL Constraint on Collection Elements
DECLARE
TYPE EmpList IS TABLE OF emp.empno%TYPE NOT NULL;
Initializing Collections
Until you initialize it, a nested table or varray is atomically null: the
collection itself is null, not its elements.

To initialize a nested table or varray, you use a constructor, a system-

defined function with the same name as the collection type. This function
"constructs" collections from the elements passed to it

You must explicitly call a constructor for each varray and nested table
variable.

Associative arrays, the third kind of collection, do not use constructors

Constructor calls are allowed wherever function calls are allowed

Initializing Collections.........
Example: Constructor for a Nested Table
In the following example, you pass multiple elements to the constructor
CourseList(), which returns a nested table containing those elements:
DECLARE
TYPE CourseList IS TABLE OF VARCHAR2(16);
my_courses CourseList;
BEGIN
my_courses :=
CourseList('Econ 2010', 'Acct 3401', 'Mgmt 3100');
END;
Because a nested table does not have a declared maximum size, you
can put as many elements in the constructor as necessary.
Initializing Collections.........
Example: Constructor for a Varray
In this example, you pass three objects to constructor ProjectList(), which
returns a varray containing those objects:
DECLARE
TYPE ProjectList IS VARRAY(50) OF VARCHAR2(16);
accounting_projects ProjectList;
BEGIN
accounting_projects :=
ProjectList('Expense Report', 'Outsourcing', 'Auditing');
END;
You need not initialize the whole varray. For example, if a varray has
a maximum size of 50, you can pass fewer than 50 elements to its
constructor.
Initializing Collections.........
Example: Nested Table Constructor Within a SQL Statement
BEGIN
INSERT INTO sophomores
VALUES (5035, 'Janet Alvarez', '122 Broad St', 'FT',
CourseList('Econ 2010', 'Acct 3401', 'Mgmt 3100'));

Example: Varray Constructor Within a SQL Statement

BEGIN
INSERT INTO department
VALUES(60, 'Security', 750400,
ProjectList('New Badges', 'Track Computers', 'Check Exits'));
Initializing Collections.........
Example: Empty Varray Constructor
If you call a constructor without arguments, you get an empty but non-
null collection
DECLARE
TYPE Clientele IS VARRAY(100) OF Customer;
vips Clientele := Clientele(); -- initialize empty varray
BEGIN
IF vips IS NOT NULL THEN -- condition yields TRUE
...
END IF;
END;
In this case, you can call the collection's EXTEND method to add
elements later.
Referencing Collection Elements
To reference an element, you specify its subscript using the syntax:

collection_name(subscript)

The allowed subscripts are:

For nested tables, 1 .. An Integer.
For varrays, 1 .. size_limit, where you specify the limit in the declaration.
For associative arrays with a numeric key, -Integer .. Integer.
For associative arrays with a string key, the length of the key and number of
possible values depends on the VARCHAR2 length limit in the type
declaration, and the database character set.
Referencing Collection Elements....
Example: Referencing a Nested Table Element

DECLARE
TYPE Roster IS TABLE OF VARCHAR2(15);
names Roster := Roster('J Hamil', 'D Caruso', 'R Singh');
j BINARY_INTEGER := 2;
BEGIN
FOR i IN names.FIRST .. names.LAST
LOOP
IF names(i) = 'J Hamil' THEN -- Referencing by Subscript
NULL;
END IF;
END LOOP;
verify_name(names(j)); -- Passing as Parameter
END;
Assigning Collections
You can assign the value of an expression to a specific element
in a collection using the syntax:

collection_name(subscript) := expression;
where expression yields a value of the type specified for
elements in the collection type definition

Collections must have the same datatype for an assignment to work.

Having the same element type is not enough.

Example: Datatype Compatibility

Assigning Collections.......
DECLARE
TYPE Clientele IS VARRAY(100) OF Customer;
TYPE Vips IS VARRAY(100) OF Customer;
-- These first two variables have the same datatype.
group1 Clientele := Clientele(...);
group2 Clientele := Clientele(...);
-- This third variable has a similar declaration,
-- but is not the same type.
group3 Vips := Vips(...);
BEGIN
-- Allowed because they have the same datatype
group2 := group1;
-- Not allowed because they have different datatypes
group3 := group2; -- Produces ERROR
END;
Comparing Collections
You can check whether a collection is null, but not test whether
two collections are the same. Conditions such as greater than,
less than, and so on are also not allowed
Example: Checking if a Collection Is Null
Nested tables and varrays can be atomically null, so they can be
tested for nullity.
DECLARE
TYPE Staff IS TABLE OF Employee;
members Staff;
BEGIN
-- Condition yields TRUE because we haven't used a
constructor.
IF members IS NULL THEN ...
END;
Comparing Collections........
Example: Comparing Two Collections
Collections cannot be directly compared for equality or inequality. For
instance, the following IF condition is not allowed:
DECLARE
TYPE Clientele IS TABLE OF VARCHAR2(64);
group1 Clientele := Clientele('Customer 1', 'Customer 2');
group2 Clientele := Clientele('Customer 1', 'Customer 3');
BEGIN
-- Equality test causes compilation error.
IF group1 = group2 THEN
...
END IF;
END;
This restriction also applies to implicit comparisons. For example,
collections cannot appear in a DISTINCT, GROUP BY, or ORDER BY list.
Using PL/SQL Collections with SQL
Statements
Example: Creating a SQL Type Corresponding to a PL/SQL Nested
Table
SQL> CREATE TYPE CourseList AS TABLE OF VARCHAR2(64);
You can use these SQL types as columns in database tables:
SQL> CREATE TABLE department (
2 name VARCHAR2(20),
3 director VARCHAR2(20),
4 office VARCHAR2(20),
5 courses CourseList)
6 NESTED TABLE courses STORE AS courses_tab;
The NESTED TABLE clause is required whenever a database table
has a nested table column. The clause identifies the nested table and
names a system-generated store table, in which Oracle stores the
nested table data.
Using PL/SQL Collections with SQL
Statements.........
Example: Inserting a Nested Table into a Database Table
BEGIN
INSERT INTO department
VALUES('English', 'Lynn Saunders', 'Breakstone Hall 205',
CourseList('Expository Writing',
'Film and Literature',
'Modern Science Fiction',
'Discursive Writing',
'Modern English Grammar',
'The Short Story',
'The American Novel'));
END;
Using PL/SQL Collections with SQL
Statements.........
Example: Retrieving a PL/SQL Nested Table from a Database Table
You can retrieve all the courses offered by the English department into
a PL/SQL nested table:

DECLARE
english_courses CourseList;
BEGIN
SELECT courses INTO english_courses FROM department
WHERE name = 'English';
END;
Using PL/SQL Collections with SQL
Statements.........
Example: Updating a Nested Table within a Database Table
You can revise the list of courses offered by the English Department:
DECLARE
new_courses CourseList :=
CourseList('Expository Writing',
'Film and Literature',
'Discursive Writing',
'Modern English Grammar',
'Realism and Naturalism',
'The Short Story',
'The American Novel',);
BEGIN
UPDATE department
SET courses = new_courses WHERE name = 'English';
END;
Manipulating Individual Collection
Elements with SQL

By default, SQL operations store and retrieve whole

collections rather than individual elements.

To manipulate the individual elements of a collection

with SQL, use the TABLE operator. The TABLE
operator uses a subquery to extract the varray or nested
table, so that the INSERT, UPDATE, or DELETE
statement applies to the nested table rather than the
top-level table.
Manipulating Individual Collection
Elements with SQL..........
Example: Inserting an Element into a Nested Table with SQL
In the following example, you add a row to the History Department
nested table stored in column COURSES:

BEGIN
-- The TABLE operator makes the statement apply to the nested
-- table from the 'History' row of the DEPARTMENT table.
INSERT INTO
TABLE(SELECT courses FROM department WHERE name =
'History')
VALUES('Modern China');
END;
Manipulating Individual Collection
Elements with SQL..........
Example: Retrieving a Single Element from a Nested Table with SQL
In the following example, you retrieve the title of a specific
course offered by the History Department:
DECLARE
my_title VARCHAR2(64);
BEGIN
-- We know that there is one history course with 'Etruscan'
-- in the title. This query retrieves the complete title
-- from the nested table of courses for the History department.
SELECT title INTO my_title
FROM
TABLE(SELECT courses FROM department WHERE name = 'History')
WHERE name LIKE '%Etruscan%';
END;
Manipulating Individual Collection
Elements with SQL..........
Example: Updating Elements Inside a Nested Table with SQL
In this example, you abbreviate the names for some courses offered by
the Psychology Department:

BEGIN
UPDATE TABLE(SELECT courses FROM department
WHERE name = 'Psychology')
SET credits = credits + adjustment
WHERE course_no IN (2200, 3540);
END;
Manipulating Individual Collection
Elements with SQL..........
Example: Deleting Elements from a Nested Table with SQL
In this example, you delete all 5-credit courses offered by the English
Department:

BEGIN
DELETE TABLE(SELECT courses FROM department
WHERE name = 'English')
WHERE credits = 5;
END;
Performing DML Operations on a
Varray with SQL
Currently, you cannot reference the individual elements of
a varray in an INSERT, UPDATE, or DELETE statement

You must retrieve the entire varray, use PL/SQL

procedural statements to add, delete, or update its elements,
and then store the changed varray back in the database
table

Example : In the next example, a stored procedure updates a

given project:
CREATE PROCEDURE update_project (
dept_no IN NUMBER,
proj_no IN NUMBER,
new_title IN VARCHAR2 DEFAULT NULL,
new_cost IN NUMBER DEFAULT NULL) AS
my_projects ProjectList;
BEGIN
SELECT projects INTO my_projects FROM department
WHERE dept_no = dept_id FOR UPDATE OF projects;
/* Find project, update it, then exit loop immediately. */
FOR i IN my_projects.FIRST..my_projects.LAST LOOP
IF my_projects(i).project_no = proj_no THEN
IF new_title IS NOT NULL THEN
my_projects(i).title := new_title;
END IF;
IF new_cost IS NOT NULL THEN
my_projects(i).cost := new_cost;
END IF;
EXIT;
END IF;
END LOOP;
UPDATE department SET projects = my_projects
WHERE dept_no = dept_id; -- Update whole Varray
END update_project;
Multilevel Collections
Multilevel Varray
declare
type t1 is varray(10) of integer;
type nt1 is varray(10) of t1; -- multilevel varray type
va t1 := t1(2,3,5);
nva nt1 := nt1(va, t1(55,6,73), t1(2,4), va);-- initialize multilevel varray
i integer;
va1 t1;
begin
i := nva(2)(3); -- multilevel access, i will get value 73
dbms_output.put_line(i);
nva.extend; -- add a new varray element to nva
nva(5) := t1(56, 32);
nva(4) := t1(45,43,67,43345);-- replace an inner varray element
nva(4)(4) := 1; -- replaces 43345 with 1 -- replace an inner integer element
end;
Multilevel Collections.....
Multilevel Nested Table
declare
type tb1 is table of varchar2(20);
type ntb1 is table of tb1; -- table of table elements
type tv1 is varray(10) of integer;
type ntb2 is table of tv1; -- table of varray elements
vtb1 tb1 := tb1('one', 'three');
vntb1 ntb1 := ntb1(vtb1);
vntb2 ntb2 := ntb2(tv1(3,5), tv1(5,7,3)); -- table of varray elements
begin
vntb1.extend;
vntb1(2) := vntb1(1);
vntb1.delete(1); -- delete the first element in vntb1
-- delete the first string from the second table in the nested table
vntb1(2).delete(1);
end;
Multilevel Collections.....
Multilevel Associative Array
declare
type tb1 is table of integer index by binary_integer;
-- the following is index-by table of index-by tables
type ntb1 is table of tb1 index by binary_integer;
type va1 is varray(10) of varchar2(20);
v1 va1 := va1('hello', 'world');
v2 ntb1;
v4 tb1;
v5 tb1; -- empty table
begin
v4(1) := 34; v4(2) := 46456;
v2(23) := v4;
v2(35) := v5; -- assign an empty table to v2(35) and try again
v2(35)(2) := 78; -- it works now
end;
Multilevel Collections.....
Multilevel Collections and BULK SQL
create type t1 is varray(10) of integer;
/
create table tab1 (c1 t1);

insert into tab1 values (t1(2,3,5));

insert into tab1 values (t1(9345, 5634, 432453));

declare
type t2 is table of t1;
v2 t2;
begin
select c1 BULK COLLECT INTO v2 from tab1;
dbms_output.put_line(v2.count); -- prints 2
end;
Collection Methods
A collection method is a built-in function or procedure that operates
on collections and is called using dot notation. The syntax follows:

collection_name.method_name[(parameters)]

Collection methods cannot be called from SQL statements.

EXTEND and TRIM cannot be used with associative arrays.
EXISTS, COUNT, LIMIT, FIRST, LAST, PRIOR, and NEXT are
functions; EXTEND, TRIM, and DELETE are procedures.
EXISTS, PRIOR, NEXT, TRIM, EXTEND, and DELETE take
parameters corresponding to collection subscripts, which are
usually integers but can also be strings for associative arrays.
Collection Methods........
EXISTS(n) - Returns TRUE if the specified element exists.
COUNT - Returns the number of elements in the collection.
LIMIT - Returns the maximum number of elements for a VARRAY, or
NULL for nested tables.
FIRST - Returns the index of the first element in the collection.
LAST - Returns the index of the last element in the collection.
PRIOR(n) - Returns the index of the element prior to the specified element.
NEXT(n) - Returns the index of the next element after the specified element.
EXTEND(n) - Appends a single null element to the collection.
TRIM(n) - Removes a single element from the end of the collection.
DELETE(n) - Removess all elements from the collection.
Collection Methods Examples
IF courses.EXISTS(i) THEN courses(i) := new_course; END IF;
IF projects.COUNT = 25 THEN ...
IF projects.LIMIT = 25 THEN ...
IF (projects.COUNT + 15) < projects.LIMIT THEN ...
FOR i IN courses.FIRST..courses.LAST LOOP ...
n := courses.PRIOR(courses.FIRST); -- assigns NULL to n
courses.EXTEND(5); -- appends 5 null elements to nested table
courses
courses.TRIM(3); -- removes last 3 elements from courses
projects.DELETE; -- deletes all elements
courses.DELETE(2); -- deletes element 2
courses.DELETE(3,6); -- deletes elements 3 through 6
Applying methods to Collection
parameters
Within a subprogram, a collection parameter assumes the properties of the
argument bound to it. So, you can apply the built-in collection methods
(FIRST, LAST, COUNT, and so on) to such parameters. In the following
example, a nested table is declared as the formal parameter of a packaged
procedure:
CREATE PACKAGE personnel AS
TYPE Staff IS TABLE OF Employee;
PROCEDURE award_bonuses (members IN Staff);
END personnel;
CREATE PACKAGE BODY personnel AS
PROCEDURE award_bonuses (members IN Staff) IS
BEGIN
IF members.COUNT > 10 THEN -- apply method
...
END IF;
END;
END personnel;