Skip to content

ABAP Keyword Documentation →  ABAP − Reference →  Processing Internal Data →  Internal Tables →  Processing Statements for Internal Tables →  READ TABLE itab 

READ TABLE - free_key

Quick Reference

Other versions: 7.31 | 7.40 | 7.54

Syntax


 ... WITH KEY {
comp1 = operand1
comp2 = operand2 ... [BINARY SEARCH] } 

           | {
keyname COMPONENTS
comp1 = operand1 comp2 = operand2 ... } ...

Variants

1. ... WITH KEY comp1 = operand1 comp2 = operand2 ... [BINARY SEARCH] ...

2. ... WITH KEY keyname COMPONENTS comp1 = operand1 comp2 = operand2 ... .

Effect

Specifies a free search key. The free search key can be defined freely or linked to the specification of a secondary table key in keyname.


Notes

  • Table expressions enable reads to be performed in operand positions too. The free key search is used whenever components are specified without an explicit key specified.
  • Outside of classes, the two obsolete variants of the addition WITH KEY are possible.

Variant 1

... WITH KEY comp1 = operand1 comp2 = operand2 ... [BINARY SEARCH] ...

Addition

... BINARY SEARCH

Effect

Components comp1 comp2 ... can be specified as search keys after the addition WITH KEY, following the rules here. An operand operand1 operand2 ... is assigned to each of these search keys and must be compatible with the data type of the component (or convertible to this data type). No duplicate or overlapping key specifications can be made.

operand1 operand2 ... are general expression positions. If necessary, the content of the operands is converted to the data type of the components before the comparison. If an arithmetic expression is specified, the calculation type is determined from its operands and the data type of the component and the result, if necessary, is converted to the data type of the component.

The first row of the internal table is searched for whose values in the specified components (or their subareas or attributes) match the values in the assigned operands operand1 operand2 ...

The search runs as follows for the individual table categories, without BINARY SEARCH being specified:

  • Standard tables are searched in a linear fashion.
  • Sorted tables are searched in a binary fashion if the specified search key is an initial part of the primary table key or includes this key; otherwise the search is linear.
  • The hash algorithm is used for hashed tables if the specified search key is an initial part of the primary table key or includes this key; otherwise the search is linear.

If the name field of a component comp is initial, the first row that matches the search key is read. If all name fields are initial, the first row of the internal table is read.

When a row is found, the system field sy-tabix is set as specified by the table category:

  • For index tables it is set to the number of rows found in the primary table index
  • For hashed tables it is set to the value 0.

If no row is found, sy-tabix is undefined (-1), except when the complete table key or the addition BINARY SEARCH is specified in a sorted table. In this case, sy-tabix is set to the row number of the entry in the primary table index in front of which the row would be inserted using INSERT ... INDEX ..., to preserve the sort.


Notes

  • If the row type of the internal table is not known statically, the components of the search key can only be specified dynamically and not directly.
  • If the search key includes components that supply a secondary table key of the internal table without the key being specified in keyname, a warning is raised by the syntax check.
  • If there are multiple hits (due to an incomplete search key or duplicate entries in the table), binary searches (using the addition BINARY SEARCH in standard tables; automatic in sorted tables) also return the first hit in accordance with the order of the rows in the primary index. This is the row with the lowest row number.
  • If WITH KEY is used, note that the values of incompatible operands operand1 operand2 ... are converted to the data type of the columns before the comparison. This means that the comparison rules do not apply to incompatible data types. If a WHERE condition is used in the statements LOOP, MODIFY, and DELETE, however, the comparison rules do apply, which can produce differing results.


Example

The internal table html_viewer_tab contains references to HTML controls. The READ statement reads the reference that points to a HTML control in a specific container control.

DATA: container   TYPE REF TO cl_gui_container, 
      html_viewer TYPE REF TO cl_gui_html_viewer. 

DATA html_viewer_tab LIKE TABLE OF html_viewer WITH EMPTY KEY. 

... 

CREATE OBJECT html_viewer EXPORTING parent = container. 
APPEND html_viewer TO html_viewer_tab. 

... 

READ TABLE html_viewer_tab 
           WITH KEY table_line->parent = container 
           INTO html_viewer. 

...

Addition

... BINARY SEARCH

Effect

The addition BINARY SEARCH produces a binary search of the table, not linear. In the case of large tables (from approximately 100 entries), this can significantly reduce runtime. The table must, however, be sorted in ascending order by the components specified in the search key. The priority of the sort order must match exactly the order of the components in the search key. If this requirement is not met, the correct row is not usually found.

  • The addition BINARY SEARCH is recommended for standard tables where no appropriate sorted secondary table key is defined.
  • The addition BINARY SEARCH can only be specified for sorted tables if the specified search key is in the correct order and is an initial part of the table key, or includes the key. It has no special effect in this situation.
  • The addition BINARY SEARCH cannot be specified for hashed tables.


Notes

  • The statement READ always uses the addition BINARY SEARCH to perform an index access; this index access can therefore only be used for tables with the appropriate type. Formal parameters or a field symbol must have at least the generic type INDEX TABLE.
  • The addition BINARY SEARCH is based on standard sorting according to the size of the components. Text sorting with the addition AS TEXT of the statement SORT can produce unexpected results, since the result for text-like components no longer depends on the binary representation, but on the locale of the current text environment.
  • The method READ_BINARY_SEARCH_CHECK of the class CL_ABAP_ITAB_UTILITIES can be used to verify whether the required sort exists for the addition BINARY SEARCH.
  • When the addition BINARY SEARCH is used, if there are multiple hits (due to an incomplete search key or duplicate entries in the table), the first hit according to the order of the rows in the primary index is returned. This is the row with the lowest row number.
  • Instead of using the addition BINARY SEARCH, it is best to work either with sorted tables or with sorted secondary table keys.


Example

Reads a table row with BINARY SEARCH after the table has been sorted accordingly. However, if possible sflight_tab should be created as a sorted table, or given a sorted secondary key afterwards (see example below).

DATA sflight_tab TYPE STANDARD TABLE OF sflight WITH EMPTY KEY. 

... 

SORT sflight_tab BY carrid connid fldate. 

READ TABLE sflight_tab 
     WITH KEY carrid = '...' connid = '...' fldate = '...' 
     BINARY SEARCH 
     ASSIGNING FIELD-SYMBOL(<flight>).

Variant 2

... WITH KEY keyname COMPONENTS comp1 = operand1 comp2 = operand2 ...

Effect

keyname can be used to specify a table key. The same applies when specifying the components as in the variant without specifying keys.

If a secondary table key is specified in keyname, the behavior is as follows:

  • If a sorted key is specified, the specified search key must be an initial part of the secondary table key or include it. The associated secondary table index is then searched in a binary fashion. If multiple entries are found when using a non-unique search key, the first hit, that is the row with the lowest row number, is read in the secondary index. Additional search criteria can also be specified which are also evaluated.
  • If a hash key is specified, the specified search key must include the secondary table key and the hash algorithm is used. Additional search criteria can also be specified which are also evaluated.

When a row is found, the system field sy-tabix is set with respect to the specified secondary table key:

  • For sorted secondary keys, it is set to the number of the found row in the corresponding secondary table index
  • For hash keys it is set to the value 0.

If no row is found, sy-tabix is undefined (-1), except when it is covered in full by a sorted secondary key. In this case, sy-tabix is set to the row number of the entry in the secondary table index in front of which the row would be inserted using INSERT ... INDEX ..., to preserve the sort.

If the primary table key is specified in keyname under the name primary_key, the behavior is the same as in the variant without keys specified.


Notes

  • When free keys are specified, secondary table keys differ from the table_key variant (for specifying the table key) by making it possible to specify additional conditions in the search key. These conditions can reduce the length of the hit list. For secondary sorted keys, however, free search keys make it possible to specify an incomplete search key, which can make the hit list longer.
  • If a secondary table key is used, when the value of sy-tabix is used subsequently as an index specification in other processing statements for the internal table, it must be ensured that the same table key is used.


Example

Reads a table row using the sorted secondary table key dbkey. The read is now performed automatically using a binary search (like the example above where BINARY SEARCH is specified explicitly) and an explicit sort is not necessary.

DATA sflight_tab TYPE STANDARD TABLE OF sflight WITH EMPTY KEY 
                 WITH UNIQUE SORTED KEY dbkey 
                      COMPONENTS carrid connid fldate. 

... 

READ TABLE sflight_tab WITH KEY dbkey 
     COMPONENTS carrid = '...' connid = '...' fldate = '...' 
     ASSIGNING FIELD-SYMBOL(<flight>).

Example

The DEMO_SECONDARY_KEYS program demonstrates the specification of a secondary table key compared to the completely free specification of a key and the resulting performance benefits.