Sintaxe INSERT

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 MariaDB.

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 "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 MariaDB). 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 MariaDB 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. Leia "Sintaxe INSERT DELAYED". Note que LOW_PRIORITY não deve normalmente ser usado com tabelas MyISAM ja que elas disabilitam inserções concorrentes. Leia "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 MariaDB 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 MariaDB 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 MariaDB 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. Leia "Opções típicas do configure".
• Você pode encontrar o valor usado por uma coluna AUTO_INCREMENT com a função mysql_insert_id. Leia "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.

Retornar