PL/SQL 101: Understanding Ref Cursors
Often on the forum we get a question along the lines of:
"I'm passing a ref cursor back from a function, how do I use the data in that ref cursor in my select statement/query"
And, equally as often, the problem comes from a lack of understanding what a ref cursor actually is. So I thought I'd give a quick summary of the basics behind ref cursors with a view to giving a clearer understanding of them. (Please excuse any errors or ommissions)
1. What is a ref cursor and how is the data fetched
Let's start with a simple function that opens a ref cursor and passes it back..
(We'll just select some employee details for a specified department)
SQL> create or replace function get_dept_emps(p_deptno in number) return sys_refcursor is
2 v_rc sys_refcursor;
3 begin
4 open v_rc for 'select empno, ename, mgr, sal from emp where deptno = :deptno' using p_deptno;
5 return v_rc;
6 end;
7 /
Function created.
Now, if we look at using this through SQL*Plus we first create ourselves a ref cursor variable to accept the results of the function, and then call the function to get the ref cursor back..
(Note: SQL*Plus variable type of "refcursor" is the equivalent of PL/SQL's "sys_refcursor")
SQL> var rc refcursor
SQL> exec :rc := get_dept_emps(10);
PL/SQL procedure successfully completed.
Ok, so our variable "rc" has our ref cursor.
If we use SQL*Plus' print command now we get..
SQL> print rc;
EMPNO ENAME MGR SAL
7782 CLARK 7839 2450
7839 KING 5000
7934 MILLER 7782 1300
Brilliant, so our ref cursor returns the rows we wanted from the employee table.
Let's look at that again..
SQL> print rc;
SP2-0625: Error printing variable "rc"
Uh oh! What's happened here? Why can't we print the data that's in our ref cursor again?
A common mistake is that people believe that a ref cursor actually contains the result data from the query. In truth, the ref cursor doesn't contain any data at all, it's just a pointer to the query.
So why did the first print statement print out the results?
SQL*Plus looked at the ref cursor and saw that it was an open cursor. As such it went into a loop, fetching each row of data from the database, using the ref cursor as it's reference (pointer) to the relevant query, and displaying each row of data until it had no more rows to fetch. Once it's fetched all the rows it closes the cursor. The power of SQL*Plus's "print" command eh!
Therefore, when we tried to print the ref cursor a second time, we got an error because SQL*Plus looked at the cursor, saw it was not an open cursor and couldn't perform the task of printing anything. Let's look at this in a bit more detail so it's a little clearer.
We'll use some PL/SQL code so that we can see the type of thing SQL*Plus us doing internally..
Firstly, let's get the open cursor and ask it how many rows it has..
SQL> ed
Wrote file afiedt.buf
1 declare
2 v_rc sys_refcursor;
3 begin
4 v_rc := get_dept_emps(10);
5 dbms_output.put_line('Rows: '||v_rc%ROWCOUNT);
6 close v_rc;
7* end;
SQL> /
Rows: 0
PL/SQL procedure successfully completed.
Yep, sure enough it's reporting 0 rows.
It's important that we remember that ROWCOUNT reports how many rows have been fetched through the cursor. Just after opening the cursor we haven't fetched any rows yet. If we fetch a row of data then we can see this change..
SQL> ed
Wrote file afiedt.buf
1 declare
2 v_rc sys_refcursor;
3 v_empno number;
4 v_ename varchar2(10);
5 v_mgr number;
6 v_sal number;
7 begin
8 v_rc := get_dept_emps(10);
9 dbms_output.put_line('Pre Fetch: Rows: '||v_rc%ROWCOUNT);
10 fetch v_rc into v_empno, v_ename, v_mgr, v_sal;
11 dbms_output.put_line('Post Fetch: Rows: '||v_rc%ROWCOUNT);
12 close v_rc;
13* end;
SQL> /
Pre Fetch: Rows: 0
Post Fetch: Rows: 1
PL/SQL procedure successfully completed.
So let's fetch all our data and display it..
SQL> ed
Wrote file afiedt.buf
1 declare
2 v_rc sys_refcursor;
3 v_empno number;
4 v_ename varchar2(10);
5 v_mgr number;
6 v_sal number;
7 begin
8 v_rc := get_dept_emps(10);
9 loop
10 fetch v_rc into v_empno, v_ename, v_mgr, v_sal;
11 exit when v_rc%NOTFOUND;
12 dbms_output.put_line('Row: '||v_rc%ROWCOUNT||' # '||v_empno||','||v_ename||','||v_mgr||','||v_sal);
13 end loop;
14 close v_rc;
15* end;
SQL> /
Row: 1 # 7782,CLARK,7839,2450
Row: 2 # 7839,KING,,5000
Row: 3 # 7934,MILLER,7782,1300
PL/SQL procedure successfully completed.
And what happens if we try and fetch more data after it's finished, just like we tried to do in SQL*Plus..
SQL> ed
Wrote file afiedt.buf
1 declare
2 v_rc sys_refcursor;
3 v_empno number;
4 v_ename varchar2(10);
5 v_mgr number;
6 v_sal number;
7 begin
8 v_rc := get_dept_emps(10);
9 loop
10 fetch v_rc into v_empno, v_ename, v_mgr, v_sal;
11 exit when v_rc%NOTFOUND;
12 dbms_output.put_line('Row: '||v_rc%ROWCOUNT||' # '||v_empno||','||v_ename||','||v_mgr||','||v_sal);
13 end loop;
14 close v_rc;
15 fetch v_rc into v_empno, v_ename, v_mgr, v_sal;
16* end;
SQL> /
Row: 1 # 7782,CLARK,7839,2450
Row: 2 # 7839,KING,,5000
Row: 3 # 7934,MILLER,7782,1300
declare
*
ERROR at line 1:
ORA-01001: invalid cursor
ORA-06512: at line 15
As expected we get an error.
So now we understand the basics of what a ref cursor is.
You can clearly see that it is just a pointer to the query and it doesn't contain any data itself, it just allows us to reference the query so that we can fetch data as we require it.
2. How can we use a ref cursor in a SQL query?
Ok, so now you've got your ref cursor you want to use it. But how can you fetch the data from the ref cursor inside another SQL Select statement?
Perhaps we can just select from it?
SQL> select * from get_dept_emps(10);
select * from get_dept_emps(10)
*
ERROR at line 1:
ORA-00933: SQL command not properly ended
Nope. How about if we tell SQL to treat it as a table?
SQL> select * from table(get_dept_emps(10));
select * from table(get_dept_emps(10))
*
ERROR at line 1:
ORA-22905: cannot access rows from a non-nested table item
What about using it as a set of data in an IN condition?
SQL> select * from emp where empno in (get_dept_emps(10));
select * from emp where empno in (get_dept_emps(10))
*
ERROR at line 1:
ORA-00932: inconsistent datatypes: expected - got CURSER
N.B. The spelling error of "CURSER" is Oracle's, not mine.
(Ok, I know the ref cursor is referencing more than just the empno in that example, but it would still result in the same error if it just referenced the empno)
The problem we're having is because the ref cursor isn't a table of data either in the literal database sense or in an array sense, and it's not a set of data that can be compared with the IN clause.
So what's the point in these ref cursors? Is there a way we can use them?
Yes there is..
First let's create a type structure on the database. Remember, SQL cannot access PL/SQL table structures so the type must be a database object..
SQL> create or replace type emptype as object(empno number,
2 ename varchar2(10),
3 mgr number,
4 sal number);
5 /
Type created.
SQL> create or replace type t_emptype as table of emptype;
2 /
Type created.
Ok, so we have a structure to hold a record and a type that is a table of that structure. So far so good. But in order to populate that structure with data coming from the ref cursor we can't just select from it as we saw above. Instead we need to provide some PL/SQL to actually do the fetching of data for us and populate the structure..
SQL> ed
Wrote file afiedt.buf
1 create or replace function populate_emps(deptno in number := null)
2 return t_emptype is
3 v_emptype t_emptype := t_emptype();
4 v_cnt number := 0;
5 v_rc sys_refcursor;
6 v_empno number;
7 v_ename varchar2(10);
8 v_mgr number;
9 v_sal number;
10 begin
11 v_rc := get_dept_emps(deptno);
12 loop
13 fetch v_rc into v_empno, v_ename, v_mgr, v_sal;
14 exit when v_rc%NOTFOUND;
15 v_emptype.extend;
16 v_cnt := v_cnt + 1;
17 v_emptype(v_cnt) := emptype(v_empno, v_ename, v_mgr, v_sal);
18 end loop;
19 close v_rc;
20 return v_emptype;
21* end;
SQL> /
Function created.
The above function calls the function that opens the ref cursor, then loops through, fetching each row and populating our SQL type structure. When all rows have been fetched, the ref cursor is closed and the SQL table structure is passed back from the function.
So now we have something in an structure that SQL understands, we should be able to query directly from it..
SQL> select * from table(populate_emps(30));
EMPNO ENAME MGR SAL
7499 ALLEN 7698 1600
7521 WARD 7698 1250
7654 MARTIN 7698 1250
7698 BLAKE 7839 2850
7844 TURNER 7698 1500
7900 JAMES 7698 950
6 rows selected.
and
SQL> select * from emp where empno in (select empno from table(populate_emps(30)));
EMPNO ENAME JOB MGR HIREDATE SAL COMM DEPTNO
7499 ALLEN SALESMAN 7698 20-FEB-1981 1600 300 30
7521 WARD SALESMAN 7698 22-FEB-1981 1250 500 30
7654 MARTIN SALESMAN 7698 28-SEP-1981 1250 1400 30
7698 BLAKE MANAGER 7839 01-MAY-1981 2850 30
7844 TURNER SALESMAN 7698 08-SEP-1981 1500 0 30
7900 JAMES CLERK 7698 03-DEC-1981 950 30
6 rows selected.
Hoorah!
We've successfully taken our ref cursor (pointer) and used it to fetch the data back that we want in a structure that SQL can understand. Ok, the examples are pretty meaningless as they stand as we could easily have achieved the same results through a basic select, but the method is what is important to understand here.
3. What is the point of ref cursors?
A good question. Many people learn about ref cursors and then try and use them everywhere. Although I personally know how to write and use ref cursors, I've found very little use for them in my production code. If you are thinking of using a ref cursor, the first thing you should ask yourself is "Why do I need one?"
If your answer is that you need to write your code to dynamically generate SQL, then perhaps you should look at what you are trying to achieve. Typically dynamic SQL, in a lot of cases, is unnecessary and a major cause of unmaintainable and unscalable code as well as possible performance issues and SQL injection.
If you really have a valid need to dynamically create SQL and you fully understand the implications and risks involved, then a ref cursor is useful for this task. What you will find however is that you are limited with ref cursors to a fixed result structure, so it may not be as generic a solution as you had initially planned for. If you consider the examples from above, you will see that we had to define a SQL structure of known columns in order to receive the data from the ref cursor. So, whilst the function that opens the ref cursor could do so for any piece of query text, the only way of successfully getting the data out of that ref cursor is to know what columns we are expecting back from it.
There is a way around this however. Either use the DBMS_SQL package to dynamically generate and process your queries or, from 11g onwards, take your ref cursor and convert it to a DBMS_SQL cursor using 11g's new DBMS_SQL.TO_CURSOR_NUMBER feature (http://download.oracle.com/docs/cd/B28359_01/appdev.111/b28419/d_sql.htm#CHDJDGDG).
DBMS_SQL is a very powerful way of writing dynamic SQL, but that's for another article.
Summary
In summary, the one key thing to remember is..
REF CURSORS ARE NOT DATA CONTAINERS. ONCE OPENED, THEY ARE SIMPLY A POINTER TO A QUERY THAT HAS YET TO FETCH DATA.
Other articles in the PL/SQL 101 series:
PL/SQL 101 : Exception Handling
PL/SQL 101 : Cursors and SQL Projection
PL/SQL 101 : DBMS_OUTPUT
PL/SQL 101 : WITH Clause
PL/SQL 101 : DataTypes - DATE
PL/SQL 101 : DataTypes - NUMBER
PL/SQL 101 : Substitution vs. Bind Variables
PL/SQL 101 : Grouping Sequence Ranges (Tabibitosan Method)