INSERT [LOW_PRIORITY | DELAYED] [IGNORE] [INTO] nome_tabela [(nome_coluna,...)] VALUES ((expressão | DEFAULT),...),(...),... [ ON DUPLICATE KEY UPDATE nome_coluna=expressão, ... ] or INSERT [LOW_PRIORITY | DELAYED] [IGNORE] [INTO] nome_tabela [(nome_coluna,...)] SELECT ... or INSERT [LOW_PRIORITY | DELAYED] [IGNORE] [INTO] nome_tabela SET nome_coluna=(expressão | DEFAULT), ... [ ON DUPLICATE KEY UPDATE nome_coluna=expressão, ... ]
INSERT
insere novos registros em uma tabela
existente. A forma INSERT ... VALUES
da
instrução insere registros baseado em valores especificados
explicitamente. A forma INSERT ... SELECT
insere linhas selecionadas de outra(s) tabela(s). A forma
INSERT ... VALUES
com listas de múltiplos
valores é suportado a partir da versão 3.22.5. A sintaxe
nome_coluna=expressão
é suportada a partir
da verão 3.22.10 do MySQL.
nome_tabela
é a tabela na qual as linhas
serão inseridas. A lista de nome das colunas ou a cláusula
SET
indica para quais colunas a instrução
especifica valor:
Se você não especificar a lista de colunas para
INSERT ... VALUES
ou INSERT ...
SELECT
, os valores para todas as colunas na tabela
devem ser fornecidos na lista VALUES()
ou
pelo SELECT
. Se você não souber a ordem
das colunas nas tabelas, use DESCRIBE
nome_tabela
para descobrir.
Qualquer coluna que não tiver o valor fornecido
explicitamente assumirá o seu valor padrão. Por exemplo,
se você especificar uma lista de colunas que não definem
todas as coolunas na tabela, às colunas não definidas
serão atribuídos o seu valor padrão. Atribuição de
valor padrão é definido em Secção 6.5.3, “Sintaxe CREATE TABLE
”.
Você também pode utilizar a palavra-chave
DEFAULT
para atribuir o valor padrão a
uma coluna (Novo na versão 4.0.3. do MySQL). Fica mais
fácil de se escrever instruções INSERT
que atribuem valor a apenas algumas colunas porque ele
permite que você evite escrever uma lista
VALUES()
incompleta (uma lista que não
inclu um valor para cada coluna da tabela). De outa forma,
você teria que escrever a lista de nomes de colunas
correspondentes a cada valor na lista
VALUES()
.
MySQL sempre tem uma valor padrão para todos os campos. Isto é algo imposto pelo MySQL para estar apto a funcionar com tabelas transacionais e não transcaionais.
Nossa visão é que a verificação do conteúdo dos campos deve ser feita pela application and not in the database server.
Uma expressão
pode se referir a qualquer
coluna que tenha sida definaida anteriormente na lista de
valores. Por exemplo, você pode dizer:
mysql> INSERT INTO nome_tabela (col1,col2) VALUES(15,col1*2);
Mas não:
mysql> INSERT INTO nome_tabela (col1,col2) VALUES(col2*2,15);
Se você especificar a palavra chave
DELAYED
, o servidor coloca a linha ou
linhas a serem inseridas em um buffer, e o cliente que envia
a instrução INSERT DELAYED
então pode
contiuar. Se a tabela está ocupada, o servidor guarda a
linha. Quando a tabela fica livre, ele começa a inserir
linhas, verificando periódicamente para ver se há novos
pedidos de leitura para a tabela. Se houver, a fila de
linhas atrasadas é suspensa até que a tabela fique livre
de novo.
Se você especificar a palavra-chave
LOW_PRIORITY
, a execução do
INSERT
é atrasada até que nenhum outro
cliente esteja lendo a tabela. Isto inclui outros clientes
que começam a ler enquanto clientes existentes já estão
lendo e enquanto a instrução INSERT
LOW_PRIORITY
está esperando. É possível,
consequentemente, para um cliente que envia uma instrução
INSERT LOW_PRIORITY
esperar por um tempo
muito longo (ou mesmo para sempre) em um ambiente de muita
leitura. (É diferente de INSERT DELAYED
,
que deixa o cliente continuar de uma vez. See
Secção 6.4.3.2, “Sintaxe INSERT DELAYED
”. Note que
LOW_PRIORITY
não deve normalmente ser
usado com tabelas MyISAM
ja que elas
disabilitam inserções concorrentes. See
Secção 7.1, “Tabelas MyISAM
”.
Se você especificar a palavra-chave
IGNORE
em um INSERT
com muitas linhas, quqlquer linha que duplicar uma chave
PRIMARY
ou UNIQUE
existente em uma tabela são ignorados e não são
inseridos. Se você não especificar
IGNORE
, a inserção é abortada se
houver quqlquer linhq que duplique um valor de uma chave
existente. Você pode determinar com função
mysql_info()
da API C quantas linhas
foram inseridas nas tabelas.
Se você especificar se uma cláusula ON DUPLICATE
KEY UPDATE
(noca no MySQL 4.1.0), e uma linha que
causasse a duplicação de um valor fosse inserida em uma
chave PRIMARY
ou
UNIQUE
, um UPDATE
da
linha antiga seria realizado. Por exemplo, o comando:
mysql>INSERT INTO table (a,b,c) VALUES (1,2,3)
->ON DUPLICATE KEY UPDATE c=c+1;
no caso da coluna a
ser declarada como
UNIQUE
e ja existir o valor
1
, o exemplo acima seria idêntico a
mysql> UPDATE table SET c=c+1 WHERE a=1;
Nota: se a coluna
b
também for única, o comando
UPDATE
seria escrito como
mysql> UPDATE table SET c=c+1 WHERE a=1 OR b=2 LIMIT 1;
e se a=1 OR b=2
casasse com diversas
linhas, somente uma linha
será atualizada! em geral, deve-se tentar evitar utilizar a
cláusula ON DUPLICATE KEY
em tabelas com
múltiplas chaves UNIQUE
.
Desde o MySQL 4.1.1 pode-se utilizar a função
VALUES(nome_coluna)
para se referir ao
valor da coluna na parte INSERT
do
comando INSERT ... UPDATE
- que é o
valor que seria inserido se não houvesse conflitos de
chaves duplicadas. Esta função é especialmente útil em
inserções de múltiplas linhas. Naturalmente a função
VALUES()
só tem sentido em um comando
INSERT ... UPDATE
e retorna
NULL
no caso de outros comandos.
Exemplo:
mysql>INSERT INTO table (a,b,c) VALUES (1,2,3),(4,5,6)
->ON DUPLICATE KEY UPDATE c=VALUES(a)+VALUES(b);
O camondo acima e idêntico a
mysql>INSERT INTO table (a,b,c) VALUES (1,2,3)
->ON DUPLICATE KEY UPDATE c=3;
mysql>INSERT INTO table (a,b,c) VALUES (4,5,6)
->ON DUPLICATE KEY UPDATE c=9;
A utilizar ON DUPLICATE KEY UPDATE
, a
opção DELAYED
é ignorada.
Se MySQL foi configurado usando a opção
DONT_USE_DEFAULT_FIELDS
, instruções
INSERT
geram um erro a menos que você
especifique valores explicitamete para todas as colunas que
exigem um valor não-NULL
. See
Secção 2.3.3, “Opções típicas do configure
”.
Você pode encontrar o valor usado por uma coluna
AUTO_INCREMENT
com a função
mysql_insert_id
. See
Secção 12.1.3.32, “mysql_insert_id()
”.
Se você utilizar instruções INSERT ...
SELECT
ou INSERT ... VALUES
com
lista de valores múltiplos, você pode utilizar a função
mysql_info()
da API C para obter informação
sobre a consulta. O formato da string de informação é
mostrado aqui:
Records: 100 Duplicates: 0 Warnings: 0
Duplicates
indica o número de linhas que
não puderam ser inseridas porque duplicariam alguns valores de
índices únicos existentes. Warnings
indica
o número de tentativas de inserção de um valor em uma coluna
que de alguma forma estava problematico. Avisos (Warnings) podem
ocorrer sob qualquer uma das seguintes condições:
Inserir NULL
em uma coluna declarada com
NOT NULL
. A coluna é definida com o seu
valor padrão.
Definir uma coluna numérica com um valor que esteja fora da faixa permitida. O valor é revertido para final apropriado da faixa.
Definir uma coluna numérica com um valor como
'10.34 a'
. O lixo no final é eliminado e
a parte numérica restante é inserida. Se o valor não
fizer sentido como um número, é atribuido
0
a coluna.
Inserir uma string em uma coluna CHAR
,
VARCHAR
, TEXT
, ou
BLOB
e que exceda o tamanho máximo da
coluna. O valor é truncado para o tamanho máximo da
coluna.
Inserir um valor em uma coluna date ou time e que seja inválido para o tipo da coluna. A coluna é preenchida com o valor de zero apropriado para o tipo.
This is a translation of the MySQL Reference Manual that can be found at dev.mysql.com. The original Reference Manual is in English, and this translation is not necessarily as up to date as the English version.