INSERT-RECORDS
Prev | Functional Data Manipulation Language (FDML) | Next

## Name

INSERT-RECORDS — Insert tuples of data into a database table.Function

## Syntax

          insert-records &key into attributes values av-pairs query database =>

## Arguments and Values

`into`

  A string, symbol or symbolic SQL expression representing the name of a table existing in `database`.

`attributes`

  A list of attribute identifiers or `NIL`.

`values`

  A list of attribute values or `NIL`.

`av-pairs`

  A list of attribute identifier/value pairs or `NIL`.

`query`

  A query expression or `NIL`.

`database`

  A database object. This will default to the value of *default-database*.

## Description

Inserts records into the table specified by `into` in `database` which defaults to *default-database*.

There are five ways of specifying the values inserted into each row. In the first `values` contains a list of values to insert and `attributes`, `av-pairs` and `query` are `NIL`. This can be used when values are supplied for all attributes in `into`. In the second, `attributes` is a list of column names, `values` is a corresponding list of values and `av-pairs` and `query` are `NIL`. In the third, `attributes`, `values` and `query` are `NIL` and `av-pairs` is an alist of (attribute value) pairs. In the fourth, `values`, `av-pairs` and `attributes` are `NIL` and `query` is a symbolic SQL query expression in which the selected columns also exist in `into`. In the fifth method, `values` and `av-pairs` are nil and `attributes` is a list of column names and `query` is a symbolic SQL query expression which returns values for the specified columns.

## Examples

    (select [first-name] [last-name] [email]
            :from [employee]
            :where [= [emplid] 11]
            :field-names nil)
    => NIL
    (insert-records :into [employee]
                    :attributes '(emplid groupid first_name last_name email
                                  ecompanyid managerid)
                    :values '(11 1 "Yuri" "Gagarin" "gagarin@soviet.org"
                              1 1))
    =>
    (select [first-name] [last-name] [email]
            :from [employee]
            :where [= [emplid] 11]
            :field-names nil)
    => (("Yuri" "Gagarin" "gagarin@soviet.org"))

## Side Effects

Modifications are made to the underlying database.

## Affected by

None.

## Exceptional Situations

An error of type sql-database-data-error is signalled if `table` is not an existing table in `database` or if the specified attributes are not found.

## See Also

`update-records`
`delete-records`

## Notes

None.

Prev | Up | Next
CACHE-TABLE-QUERIES | Home | UPDATE-RECORDS