< previous page page_176 next page > Page 176 Syntax for DESCRIBE The syntax for the DESCRIBE command looks like this: DESC[RIBE] [schema. ]object_name[@database_link_name] where: DESC[RIBE] Is the command, which may be abbreviated to DESC. schema Is the name of the object's owner. This defaults to your username. object_name Is the name of the object, often a table or a view, that you want to describe. You can describe any of the following: a table, a view, a stored procedure, a stored function, a stored package, or an Oracle8 object type. database_link_name Is the name of a database link pointing to the database where the object exists. You only need to use this if the object you want to describe exists in a database other than the one to which you are currently connected. Your DBA can help create a database link if you need one. Describing a Table DESCRIBE is most often used to view the definition of a table or a view. Simply enter the command DESCRIBE, followed by the name of the table or view you are interested in, as the following example shows: SQL> DESCRIBE employee Name Null? Type EMPLOYEE_ID NOT NULL NUMBER EMPLOYEE_NAME VARCHAR2 (40) EMPLOYEE_HIRE_DATE DATE EMPLOYEE_TERMINATION_DATE DATE EMPLOYEE_BILLING_RATE NUMBER If you aren't the owner of the table, you can qualify the table or view name using the standardowner.table_name notation. This next example describes the ALL_ USERS view, which is owned by the user SYS. SQL> DESCRIBE sys.all_users Name Null? Type USERNAME NOT NULL VARCHAR2(30) USER_ID NOT NULL NUMBER CREATED NOT NULL DATE < previous page page_176 next page > < previous page page_177 next page > Page 177 As you can see, DESCRIBE just gives you a list of columns in the table or view, along with their resulting datatypes, lengths, and nullability. If you need to know more, such as whether or not a column has a default value, you will need to query the data dictionary directly. You will see how to do this later in the chapter. In early releases of Oracle8, in particular the 8.0.3 release, the DESCRIBE command does not function correctly when used with a public synonym. Thus, DESCRIBE ALL_TABLES will fail because ALL_TABLE is a public synonym. DESCRIBE SYS.ALL_TABLES will succeed because the view name is fully qualified. You can also create private synonyms that match public synonyms for objects you frequently look at. Create a private synonym named ALL_TABLES that refers to SYS.ALL_TABLES, and DESCRIBE will correctly interpret it. Describing Stored Functions and Procedures DESCRIBE may also be used on stored procedures and functions. When used on a stored function, the DESCRIBE command tells you the data type of the return value, and also gives you a list of arguments that the function expects. For example: SQL> DESCRIBE terminate_employee FUNCTION terminate_employee RETURNS NUMBER(38) Argument Name Type In/Out Default? EMP_ID NUMBER IN EMP_HIRE_DATE DATE OUT EMP_TERM_DATE DATE IN As you can see, DESCRIBE returns the following information for each argument: The datatype Whether it is an input, output, or both The default value, if there is one The order in which the arguments are listed is also the order in which they should be passed into the function when you call it. The DESCRIBE command does not show you the source code for a function. To see that, you need to query the ALL_ SOURCE data dictionary view. The following example shows how to get the source for the TERMINATE_EMPLOYEE function: SQL> SELECT text 2 FROM all_source 3 WHERE owner = USER < previous page page_177 next page > < previous page page_178 next page > Page 178 4 AND name = TERMINATE_EMPLOYEE 5 ORDER BY LINE; TEXT FUNCTION terminate_employee (emp_id IN employee. employee_id%TYPE, emp_hire_date OUT employee.employee_hire_date%TYPE, emp_term_date IN employee. employee_termination_date%TYPE) RETURN INTEGER AS BEGIN UPDATE employee SET employee_termination_date = emp_term_date WHERE employee_id = emp_id; SELECT employee_hire_date INTO emp_hire_date FROM employee WHERE employee_id = emp_id; RETURN 1; EXCEPTION WHEN OTHERS THEN RETURN 0; END; 19 rows selected. Describing a procedure works the same way as describing a function. The only difference is that procedures do not have a return type. Describing Packages and Object Types With the release of Oracle8, the SQL*Plus DESCRIBE command was enhanced to return information about Oracle8 object types. The following example shows how this works: SQL> DESCRIBE employee_type Name Null? Type EMPLOYEE_NAME VARCHAR2 (40) EMPLOYEE_HIRE_DATE DATE EMPLOYEE_SALARY NUMBER (9,2) METHOD MEMBER FUNCTION TERMINATE_EMPLOYEE RETURNS NUMBER Argument Name Type In/Out Default? EMP_ID NUMBER IN EMP_TERM_DATE DATE IN Another Oracle8 enhancement provides the ability to describe a stored package and get back a list of all functions and procedures that make up the package. This < previous page page_178 next page > < previous page page_179 next page > Page 179 is not surprising, because objects and packages are very similar in nature. For example, you can get a list of all the entry points in the DBMS_OUTPUT package by using DESCRIBE as shown here: SQL> DESCRIBE sys.dbms_ output PROCEDURE DISABLE PROCEDURE ENABLE Argument Name Type In/Out Default? BUFFER_SIZE NUMBER(38) IN DEFAULT PROCEDURE GET_LINE Argument Name: Type In/Out Default? LINE VARCHAR2 OUT STATUS NUMBER(38) OUT PROCEDURE GET_LINES Argument Name Type In/Out Default? LINES TABLE OF VARCHAR2(255) OUT NUMLINES NUMBER(38) IN/OUT PROCEDURE NEW_LINE As with functions and procedures, you can get at the source for a package, or for an Oracle8 object type, by querying the ALL_SOURCE view. See the previous section for an example of how this is done. There have been some problems with the enhancements to DESCRIBE. Compatibility between different versions of SQL*Plus and different versions of the Oracle server has sometimes suffered. For example, if you use the 8.0.3 version of SQL*Plus, connect to a 7.x database and issue the DESCRIBE command on a table, it will fail. This particular problem was fixed in SQL*Plus 8.0.4. Why DESCRIBE Is Not Enough Handy as DESCRIBE is, it just doesn't return enough information. While it shows you all the columns in a table, there are a lot of important details it leaves out. If you need to know the primary key for a table, DESCRIBE won't tell you. If you need to know the foreign key constraints defined on a table, DESCRIBE won't tell you that, either. DESCRIBE won't show you the indexes. DESCRIBE won't show you the default values. DESCRIBE won't show you the triggers, and DESCRIBE won't tell you anything about the table's security. How then do you get at this other information? One way is to install Oracle's Enterprise Manager software. Enterprise Manager has a GUI-based schema browser < previous page page_179 next page > < previous page page_180 next page > Page 180 that will show you everything there is to see about tables, indexes, views, triggers, and other objects. There are also several third-party software packages on the market that provide the same functionality. However, for many people, SQL*Plus is the only option available, or at least the only one conveniently available. If this is the case for you, you can still get the information you need by querying Oracle's data dictionary. Oracle's Data Dictionary Views Oracle has to keep track of all the tables, views, constraints, indexes, triggers, and other objects you create. In order to do that, Oracle needs a place to store the information. This repository of information about your database is referred to as the data dictionary. Whenever you create a new object, such as a table, Oracle stores all the information about that object in the data dictionary. Modify the object, and Oracle modifies the data dictionary. It follows, then, that if you want to know anything about your database, the data dictionary is the place to go. The data dictionary is a set of tables owned by the user SYS. The structure of these tables ends up being fairly complex, and much of the information is not stored in a very user-friendly form. You probably do not want to query these tables directly, and unless you have been given access to log in as user SYS, you won't be able to see them anyway. To help you out, Oracle provides a set of data dictionary views. These views have names that are easy to remember. The column names used in the views are also easy to remember and use a consistent naming convention. There are data dictionary views for each different type of schema object, and they present information in an easy-to-understand form. For example, if you are looking at a date column, the DBA_TAB_COLUMNS view will tell you it is of type DATE. The underlying data dictionary table, which happens to be SYS.COL $ , will simply tell you the type is 12. Oracle has a large number of data dictionary views. This chapter concentrates only on the views that are used to return information about the structure of a table, its constraints, indexes, columns, triggers, and security. This is the most common type of information needed by application developers and other database users. I encourage you to dig deeper. If you want, or need, to know more, then the Oracle Server Reference manual would be a good place to start. The Oracle Server Reference manual contains a chapter titled Static Data Dictionary Views, which gives a comprehensive list of all the views available. The View Types: ALL, DBA, and USER There are three different types of data dictionary views you need to be aware of. These control the scope of the information you can look at. The three view types are: < previous page page_180 next page > < previous page page_181 next page > Page 181 USER The USER views show you information only about objects that you own. There is a USER_TABLES view, for example, that will list only tables you own. ALL The ALL views show you information about all objects you are able to access. Anything you own will be included in an ALL view, as well as anything owned by other users, but to which you have been granted access. DBA The DBA views show you information about all objectsperiod. Usually only database administrators will have access to these views, and they could be considered a superset of the ALL views. DBA_TABLES, for example, will list every single table that exists. The typical way to gain access to the DBA views is to be granted the DBA role. However, the SELECT ANY TABLE privilege will also let you see them. Generally speaking, for any given object type, one view of each type will exist. It's up to you to choose the one you want to look at. Table 6-1 shows how this works in terms of the views discussed in this chapter. Table 6-1. Correspondence Between USER, ALL, and DBA Views USER View Name ALL View Name DBA View Name USER_TABLES ALL_TABLES DBA_TABLES USER_TAB_COLUMNS ALL_TAB_COLUMNS DBA_TAB_COLUMNS USER_CONSTRAINTS ALL_CONSTRAINTS DBA_CONSTRAINTS USER_CONS_COLUMNS ALL-CONS_COLUMNS DBA_CONS_COLUMNS USER_INDEXES ALL_INDEXES DBA_INDEXES USER_IND_COLUMNS ALL_IND_COLUMNS DBA-IND_COLUMNS USER-SYNONYMS ALL_SYNONYMS DBA_SYNONYMS USER_TRIGGERS ALL_TRIGGERS DBA_TRIGGERS USER_TAB_PRIVS ALL_TAB_PRIVS DBA_TAB_PRIVS As you delve more deeply into Oracle's data dictionary, you will occasionally find instances when corresponding views do not exist in all three categories. When a view is omitted it's either for security reasons, because it doesn't make sense in the context of a particular object, or because it would be redundant. The USER_JOBS and DBA_JOBS views provide a good example of this. A user can own a job, hence the USER_JOBS view. The database administrator needs to see everything, hence the DBA_JOBS view. There is no ALL_JOBS view, because there is no mechanism to grant another user access to your jobs. ALL_JOBS would be redundant with USER_JOBS, because the only jobs you can ever see are your own anyway. < previous page page_181 next page > < previous page page_182 next page > Page 182 When you write scripts, avoid the DBA views if at all possible. Using the DBA views limits your ability to share your scripts, because most users don't have access to them. Which view should you use? The USER views limit you to seeing information only about objects that you own. If I'm working interactively, I'll frequently use the USER views to save myself some typing, because I don't need to enter a WHERE clause to restrict the results to my objects. When writing scripts, I try to use the ALL views in order to make the scripts more flexible. It's not unusual, for example, to need to see the definition for a table owned by another user. The ALL views allow this. I save the DBA views for database administrationrelated tasks. The following sections show you how to get information about various types of schema objects. First I'll show how to list the tables you own and how to look at the column definitions for those tables. Next you will see how to look at the constraints, indexes, triggers, synonyms, and security for a table. Finally, you will see how to write one script that will give you a pretty complete dump of all this information just by issuing one command. Dictionary Views Used in This Chapter. A number of data dictionary views are referenced by the examples and scripts shown in this chapter. For your convenience, they are all shown together in this section. As you scan through these, it's not necessary to understand every single column of each view. Many of the view columns, particularly in ALL_TABLES and ALL_INDEXES, relate to the physical implementation of the objects, and aren't discussed in this chapter. The more experienced you become with Oracle, the more you will come to understand the information these columns contain. The ALL_TABLES View The ALL_TABLES view contains one record for every table to which you have access. Table 6-2 lists the columns in this view and explains what information they contain. Many of the columns contain information about the physical implementation of the table, and if you are not the DBA, you may not be too interested in them. Some columns, beginning with NUM_ROWS and going through NUM_FREELIST_BLOCKS, are set only when you use the ANALYZE TABLE command to compute statistics for the table. < previous page page_182 next page > < previous page page_183 next page > Page 183 Table 6-2. Columns in the ALL_TABLES View Column Name Contents OWNER Username of the table's owner. TABLE_NAME Name of the table. TABLESPACE_NAME Name of the tablespace where the table is stored. This is a foreign key to the DBA_TABLESPACES view. CLUSTER_NAME A cluster name, if the table belongs to a cluster. This is a foreign key to the ALL_CLUSTERS view. IOT_NAME An index-organized table name. PCT_FREE Minimum percentage of free space in a block. When free space drops to this level, Oracle stops adding new rows to the block. PCT_USED Minimum percentage of used space in a block. When used space drops to this level, Oracle will again add new rows to the block. INI_TRANS Initial number of transactions that can concurrently touch this block. INITIAL_EXTENT The size, in bytes, of the initial extent for the table. This is how much space is allocated when the table is first created. NEXT_EXTENT The size, in bytes, of the next extent for the table. The next time the table needs to be expanded, this is how much space will be allocated. MIN_EXTENTS The minimum number of extents to be allocated for the table. This value affects the amount of space that is initially allocated for the table. See INITIAL_EXTENT and NEXT_EXTENT. MAX_EXTENTS The maximum number of extents allowed for the table. When these are used up, you won't be able to insert any more data into the table. PCT_INCREASE A percentage that controls growth of the NEXT_EXTENT value. Each time an extent is allocated, NEXT_EXTENT is recomputed to be NEXT_EXTENT + (NEXT_EXTENT* (PCT_INCREASE/100)). This value is then rounded up to the blocksize, or a multiple of the blocksize. FREELISTS The number of freelists allocated to the table. FREELIST_GROUPS The number of freelist groups allocated to the table. LOGGING The logging attribute for the table. BACKED_UP A Y/N flag that indicates whether or not the table has been backed up since the last change. NUM_ROWS The number of rows in the table.a BLOCKS The number of data blocks used by the table.a (table continued on next page) < previous page page_183 next page > < previous page page_184 next page > Page 184 Table 6-2. Columns in the ALL_TABLES View (continued) Column Name Contents EMPTY_BLOCKS The number of data blocks allocated to the table that have never been used.a AVG_SPACE The average amount of free space in all blocks allocated to this table. This value is in bytes. CHAIN_CNT The number of rows in the table that have had to be chained across more than one block, possibly because the row has been expanded. This also includes rows that have been moved entirely out of the block in which they were originally created. AVG_ROW_LEN The average length, in bytes, of the rows in the table. AVG_SPACE_FREELIST_BLOCKS The average freespace in all table blocks that are currently in the freelist. NUM_FREELIST_BLOCKS The number of blocks allocated to the table that still contain space for more rows. DEGREE The number of threads per instance for scanning the table. INSTANCES The number of instances allowed to scan the table at one time. CACHE A Y/N flag indicating whether or not the table should be cached in the buffer. TABLE_LOCK Either ENABLED or DISABLED, indicating whether or not users are allowed to lock the entire table. SAMPLE_SIZE The sample size used when analyzing the table and computing statistics. LAST_ANALYZED The date on which the table was most recently analyzed. PARTITIONED Either YES or NO, indicating whether or not the table is partitioned. IOT_TYPE Indicates whether or not the table is an index-only table. A null value indicates a normal table. A value of IOT or IOT_OVERFLOW is used for index-only tables. TEMPORARY Either Y or N, indicating whether or not the table is a temporary table. NESTED Either YES or NO, indicating whether or not the table is a nested table. BUFFER_POOL The name of the default buffer pool for the table. a Not maintained automatically by Oracle. This column is set when you use the ANALYZE TABLE command with the COMPUTE STATISTICS option. The ALL_TAB_COLUMNS view The ALL_TAB_COLUMNS view contains one record for every column in a table. This is the view used by the DESCRIBE command to get column names, lengths, < previous page page_184 next page > < previous page page_185 next page > Page 185 and datatypes. Table 6-3 lists the columns in this view and explains the information they contain. Table 6-3. Columns in the ALL_TAB_COLUMNS View Column Name Contents OWNER Username of the table's owner. TABLE_NAME Name of the table. COLUMN_NAME The column name. DATA_TYPE The column's datatype (e.g., VARCHAR2, NUMBER, etc). DATA_TYPE_MOD The datatype modifier for the column. DATA_TYPE_OWNER The datatype owner. This is used in Oracle8 and above when you create a column based on an object type owned by another user. DATA_LENGTH The length of the column in bytes. DATA_PRECISION The decimal precision, or the number of significant digits, the column will hold, if the column is type NUMBER. If the column is type FLOAT, then this is the binary precision, or the number of significant bits. For all other datatypes, this will be NULL. DATA_SCALE The number of digits allowed to the right of the decimal point in a NUMBER column. Remember, NUMBER columns are defined as NUMBER (precision, scale). NULLABLE Y = the column may contain null values. N = the column may not contain null values. This may be because of a NOT NULL constraint, or because the column is part of the table's primary key. COLUMN_ID The sequence number, indicating the column's position within each record. When you create a table, the first column in the list will have a COLUMN_ID of 1. The next column will have a COLUMN_ID of 2, and so on. DEFAULT_LENGTH The length of the default value for the column, if there is a default value. DATA_DEFAULT The default value for the column. NUM_DISTINCT The number of distinct values in the column.a LOW_VALUE The lowest value, up to the first 32 bytes of that value, in the column.a HIGH_VALUE The highest value, up to the first 32 bytes of that value, in the column.a DENSITY The density of the column.a NUM_NULLS The number of records with a null value for this column.b NUM_BUCKETS The number of buckets in the column's histogram.b LAST_ANALYZED The date on which the data in the column was last analyzed with an ANALYZE TABLE COMPUTE STATISTICS command.b . returns the following information for each argument: The datatype Whether it is an input, output, or both The default value, if there is one The order in which the arguments are listed is also the. Object Types With the release of Oracle8 , the SQL* Plus DESCRIBE command was enhanced to return information about Oracle8 object types. The following example shows how this works: SQL& gt; DESCRIBE. versions of SQL* Plus and different versions of the Oracle server has sometimes suffered. For example, if you use the 8.0.3 version of SQL* Plus, connect to a 7.x database and issue the DESCRIBE