Pipeline functions - what happens under the hood? (10g)

Question

Hi all,
What happens when you call a pipelined function? (As opposed to a plain table-valued function.)
From what I understand, a pipelined function will return rows as they are needed. Let's say I have a really silly example of a pipelined function,
CREATE OR REPLACE PACKAGE BODY TEST_PACKAGE_1
AS
    FUNCTION GET_DATA RETURN JUST_A_TABLE PIPELINED
    IS
    BEGIN
        PIPE ROW (JUST_A_TYPE('HELLO'));
        PIPE ROW (JUST_A_TYPE('WORLD'));
        RETURN;
    END;
END TEST_PACKAGE_1;
/Then let's say I were to SELECT * FROM TABLE(TEST_PACKAGE_1.GET_DATA) WHERE ROWNUM = 1, what happens to the second row? Does the code that returns the second row still get educated? (Obviously it's omitted from the query, but does it still get generated somewhere and just go nowhere?)
If I have a cursor on a PL/SQL block that selects from GET_DATA, will each row only be returned as the cursor references it? In that case, what happens to the rows that don't get selected? If there some resource that need to be closed out (say, just before the return statement), would it still be safe to close it out?
Thanks!
Don

Answer 1

Interesting question, lets try a simple test and see we'll just take your example function and toss in a few dbms_output statements like so:
CREATE OR REPLACE PACKAGE BODY TEST_PACKAGE_1
AS
    FUNCTION GET_DATA RETURN JUST_A_TABLE PIPELINED
    IS   
    BEGIN
        dbms_output.put_line('ONE');
        PIPE ROW (JUST_A_TYPE('HELLO'));       
        dbms_output.put_line('TWO');
        PIPE ROW (JUST_A_TYPE('WORLD'));       
        dbms_output.put_line('THREE');
        RETURN;   
    END;
END TEST_PACKAGE_1;Now not forgetting to enable dbms_output call it three times like so:
SELECT * FROM TABLE(TEST_PACKAGE_1.GET_DATA) WHERE ROWNUM = 1;
SELECT * FROM TABLE(TEST_PACKAGE_1.GET_DATA) WHERE ROWNUM <= 2;
SELECT * FROM TABLE(TEST_PACKAGE_1.GET_DATA) WHERE ROWNUM <= 3;What I saw from my test was that with the first call I got 1 row of data from the pipelined function and only the first dbms_output statement was processed. For the second statement I got 2 rows of data from the function and the first two dbms_output statements were processed. For the final call I again got 2 rows of data from the function and all 3 dbms_output statements were processed.
My environment:
Oracle Database 10g Express Edition Release 10.2.0.1.0 - Product
PL/SQL Release 10.2.0.1.0 - Production
"CORE     10.2.0.1.0     Production"
TNS for 32-bit Windows: Version 10.2.0.1.0 - Production
NLSRTL Version 10.2.0.1.0 - Production