diff --git a/reference/en/modules/query_sql.xml b/reference/en/modules/query_sql.xml index 5be34db636..48afabf680 100644 --- a/reference/en/modules/query_sql.xml +++ b/reference/en/modules/query_sql.xml @@ -22,9 +22,9 @@ + .addEntity("cat", Cat.class) + .setMaxResults(50) + .list();]]> This query specified: @@ -50,9 +50,16 @@ The addJoin() method may be used to load associations to other entities - and collections. TODO: examples! + and collections. + + A native SQL query might return a simple scalar value or a combination of scalars and entities. @@ -70,14 +77,16 @@ The {cat.*} notation used above is a shorthand for "all properties". - Alternatively, you may list the columns explicity, but even then you must let Hibernate + Alternatively, you may list the columns explicity, but even this case we let Hibernate inject the SQL column aliases for each property. The placeholder for a column alias is just the property name qualified by the table alias. In the following example, we retrieve Cats from a different table (cat_log) to the one declared in the mapping metadata. Notice that we may even use the property aliases in the where clause if we like. - - The {}-syntax is not required for named queries. See more in + + + The {}-syntax is not required for named queries. + See Named SQL queries - Named SQL queries may be defined in the mapping document and called in exactly the same way - as a named HQL query. In this case, we do not need to call - addEntity(). + Named SQL queries may be defined in the mapping document and called in exactly the + same way as a named HQL query. In this case, we do not need + to call addEntity(). - + SELECT person.NAME AS {person.name}, person.AGE AS {person.age}, person.SEX AS {person.sex} - FROM PERSON person WHERE person.NAME LIKE 'Hiber%' + FROM PERSON person + WHERE person.NAME LIKE :namePattern ]]> - + + The <return-join> and <load-collection> + elements are used to join associations and define queries which initialize collections, + respectively. + + + + + + SELECT person.NAME AS {person.name}, + person.AGE AS {person.age}, + person.SEX AS {person.sex}, + adddress.STREET AS {address.street}, + adddress.CITY AS {address.city}, + adddress.STATE AS {address.state}, + adddress.ZIP AS {address.zip} + FROM PERSON person + JOIN ADDRESS adddress + ON person.ID = address.PERSON_ID AND address.TYPE='MAILING' + WHERE person.NAME LIKE :namePattern +]]> + A named SQL query may return a scalar value. You must specfy the column alias and Hibernate type using the <return-scalar> element: @@ -131,25 +164,20 @@ List loggedCats = sess.createSQLQuery(sql) FROM PERSON p WHERE p.NAME LIKE 'Hiber%' ]]> - - The <return-join> and <load-collection> - elements are used to join associations and define queries which initialize collections, - respectively. TODO! - - Using return-property to explicitly specify column/alias names - With <return-property> you can explicitly tell Hibernate what columns - to use as opposed to use {}-syntax to let Hibernate inject its own aliases. + With <return-property> you can explicitly tell Hibernate what column + aliases to use, instead of using the {}-syntax to let Hibernate inject its + own aliases. - - - + + + SELECT person.NAME AS myName, person.AGE AS myAge, @@ -158,34 +186,37 @@ List loggedCats = sess.createSQLQuery(sql) ]]> - <return-property> also works with multiple columns. This solves a limitation with - the {}-syntax which can not allow fine grained control of multi-column properties. + + <return-property> also works with multiple columns. This solves a + limitation with the {}-syntax which can not allow fine grained control + of multi-column properties. + - - - - - - - - SELECT EMPLOYEE AS {emp.employee}, EMPLOYER AS {emp.employer}, - STARTDATE AS {emp.startDate}, ENDDATE AS {emp.endDate}, - REGIONCODE as {emp.regionCode}, EID AS {emp.id}, VALUE, CURRENCY - FROM EMPLOYMENT - WHERE EMPLOYER = :id AND ENDDATE IS NULL - ORDER BY STARTDATE ASC + + + + + + + + SELECT EMPLOYEE AS {emp.employee}, EMPLOYER AS {emp.employer}, + STARTDATE AS {emp.startDate}, ENDDATE AS {emp.endDate}, + REGIONCODE as {emp.regionCode}, EID AS {emp.id}, VALUE, CURRENCY + FROM EMPLOYMENT + WHERE EMPLOYER = :id AND ENDDATE IS NULL + ORDER BY STARTDATE ASC ]]> - Notice that in this example we used <return-property> in combination - with the {}-syntax for injection. Allowing users to choose - how they want to refer column and properties. + Notice that in this example we used <return-property> in combination + with the {}-syntax for injection. Allowing users to choose + how they want to refer column and properties. - If your mapping has a discriminator you must use <return-discriminator> to specify the - discriminator column. + If your mapping has a discriminator you must use <return-discriminator> + to specify the discriminator column. @@ -193,11 +224,10 @@ List loggedCats = sess.createSQLQuery(sql) Using stored procedures for querying - Hibernate 3 introduces support for queries via stored procedures. - - The stored procedures must return a resultset as the first out-parameter to be able to work with Hibernate. - - An example of such a stored procedure in Oracle 9 and higher is as follows: + Hibernate 3 introduces support for queries via stored procedures. The stored procedures must + return a resultset as the first out-parameter to be able to work with Hibernate. An example + of such a stored procedure in Oracle 9 and higher is as follows: + + To use this query in Hibernate you need to map it via a named query. + @@ -229,7 +261,6 @@ BEGIN { ? = call selectAllEmployments() } ]]> - Notice stored procedures currently only return scalars and entities. @@ -259,14 +290,16 @@ BEGIN - The procedure must return a result set. This is done by returning a SYS_REFCURSOR in Oracle 9 - or 10. In Oracle you need to define a REF CURSOR type. + The procedure must return a result set. This is done by returning a + SYS_REFCURSOR in Oracle 9 or 10. In Oracle you + need to define a REF CURSOR type. - Recommended form is { ? = call procName(<parameters>) } or - { ? = call procName } (This is more an Oracle rule than a Hibernate rule.) + Recommended form is { ? = call procName(<parameters>) } + or { ? = call procName } (this is more an Oracle rule than a + Hibernate rule). @@ -342,9 +375,11 @@ BEGIN - You can see the expected order by enabling debug logging for the org.hiberante.persister.entity - level. With this level enabled Hibernate will print out the static SQL that is used to create, update, delete etc. entities. - To see the expected sequence, remember to not include your custom SQL in the mapping files as that will override the Hibernate generated static sql. + You can see the expected order by enabling debug logging for the + org.hibernate.persister.entity level. With this level enabled + Hibernate will print out the static SQL that is used to create, update, delete etc. + entities. (To see the expected sequence, remember to not include your custom SQL in + the mapping files as that will override the Hibernate generated static sql.) @@ -379,8 +414,11 @@ END updatePerson;]]> - - SELECT NAME AS {p.name}, ID AS {p.id} FROM PERSON WHERE ID=? FOR UPDATE + + SELECT NAME AS {pers.name}, ID AS {pers.id} + FROM PERSON + WHERE ID=? + FOR UPDATE ]]> @@ -397,30 +435,40 @@ END updatePerson;]]> ]]> - And this also works with stored procedures. + This even works with stored procedures. - TODO: Document the following example for collection loader. + You may even define a query for collection loading: - - - SELECT {empcol.*} - FROM EMPLOYMENT empcol + + + + +]]> + + + + SELECT {emp.*} + FROM EMPLOYMENT emp WHERE EMPLOYER = :id ORDER BY STARTDATE ASC, EMPLOYEE ASC - +]]> - - - - SELECT EMPLOYEE AS {emp.employee}, EMPLOYER AS {emp.employer}, - STARTDATE AS {emp.startDate}, ENDDATE AS {emp.endDate}, - REGIONCODE as {emp.regionCode}, ID AS {emp.id} - FROM EMPLOYMENT - WHERE EMPLOYER = :id AND ENDDATE IS NULL - ORDER BY STARTDATE ASC + + You could even define an entity loader that loads a collection by + join fetching: + + + + + + SELECT NAME AS {pers.*}, {emp.*} + FROM PERSON pers + LEFT OUTER JOIN EMPLOYMENT emp + ON pers.ID = emp.PERSON_ID + WHERE ID=? ]]>