[Records_Map] returns a map of maps which contain all of the results from an inline. This tag is comparable to the [Records_Array] method, but makes it easier to extract records based on their key field value or field names.

For example, results from the [Records_Map] method for a Contacts.People table might be represented as follows. The keys for the outer map are the key field values for each record from the table. The keys for the inner map are the field names for each record in the found set.

Map( '1' = Map( 'First'='John', 'Last'='Doe', 'Age'='25')),
'2' = Map( 'First'='Jane', 'Last'='Doe', 'Age'='26'))

By default the current key field name is used to determine the key field values. If a -KeyField parameter is specified for the [Records_Map] method then the values for that field are used instead. If no key field can be determined then a field named ID or the first field from the results is used.

The fields in the [Records_Map] can be pared down using -ReturnField parameters. If one or more -ReturnField parameters are specified then only those fields will be included in the inner maps. In addition, an -ExcludeField parameter can be used to knock only certain fields out of a [Records_Map].

The field names for the [Records_Map] are drawn from the values returned by the [Field_Names] method. Alternate field names can be used by specifying a -Fields parameter with an array value. Note that -ReturnField, -ExcludeField, and -KeyField should all refer to the new names rather than the original names of the fields.

The order of records is not normally preserved by the [Records_Map] method since the order of elements in a map is not defined. If the order of records is important then -Type='array' can be used to switch the outer type to an array. This array will contain pairs that correspond to the map entries from the default option.