mirror of
https://github.com/php/doc-es.git
synced 2026-03-26 00:12:06 +01:00
41bf49796f
git-svn-id: https://svn.php.net/repository/phpdoc/es/trunk@337046 c90b9560-bf6c-de11-be94-00142212c4b1
456 lines
13 KiB
XML
456 lines
13 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
|
<!-- $Revision$ -->
|
|
<!-- EN-Revision: 6c668086fab4340002143e0e68daa87609c612ea Maintainer: seros Status: ready -->
|
|
<!-- Reviewed: no Maintainer: seros -->
|
|
|
|
<refentry xml:id="mongocollection.insert" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
|
|
<refnamediv>
|
|
<refname>MongoCollection::insert</refname>
|
|
<refpurpose>Inserta un documento en la colección</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsect1 role="description">
|
|
&reftitle.description;
|
|
<methodsynopsis>
|
|
<modifier>public</modifier> <type>bool|array</type><methodname>MongoCollection::insert</methodname>
|
|
<methodparam><type>array|object</type><parameter>document</parameter></methodparam>
|
|
<methodparam choice="opt"><type>array</type><parameter>options</parameter><initializer>array()</initializer></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
Todas los string que se envíen a la base de datos deben estar en UTF-8. Si un string no estuviera
|
|
en UTF-8, se lanzará una <classname>MongoException</classname>. Para insertar
|
|
(o consultar) un texto que no esté en UTF-8, utilice <classname>MongoBinData</classname>.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="parameters">
|
|
&reftitle.parameters;
|
|
<para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<parameter>document</parameter>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Un array u objeto. Si se utiliza un objeto, este no puede tener propiedades
|
|
protegidas o privadas.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
Si el parámetro no posee una clave o propiedad <literal>_id</literal>,
|
|
se creará una nueva instancia de <classname>MongoId</classname>
|
|
y se le asignará. Este comportamiento especial no implica que el
|
|
parámetro sea pasado por referencia.
|
|
</para>
|
|
</note>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<parameter>options</parameter>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Un array de opciones para la operación de inserción. Las opciones disponibles
|
|
actualmente son:
|
|
<itemizedlist>
|
|
&mongo.writes.parameters.fsync;
|
|
&mongo.writes.parameters.journal;
|
|
&mongo.writes.parameters.sockettimeoutms;
|
|
&mongo.writes.parameters.writeconcern;
|
|
&mongo.writes.parameters.writeconcerntimeoutms;
|
|
</itemizedlist>
|
|
</para>
|
|
<para>
|
|
Las siguientes opciones están obsoletas y no deberían usarse más:
|
|
<itemizedlist>
|
|
&mongo.writes.parameters.safe;
|
|
&mongo.writes.parameters.timeout;
|
|
&mongo.writes.parameters.writeconcerntimeout;
|
|
</itemizedlist>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="returnvalues">
|
|
&reftitle.returnvalues;
|
|
<para>
|
|
Devuelve un array que contiene el estado de la inserción si la opción
|
|
<literal>"w"</literal> está establecida. De lo contrario, devuelve &true; si el
|
|
array insertado no está vacío (se lanzará una <classname>MongoException</classname>
|
|
si el array insertado está vacío).
|
|
</para>
|
|
<para>
|
|
Si devuelve un array, las siguientes claves podrían estar presentes:
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<parameter>ok</parameter>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Debería ser casi siempre 1 (a menos que last_error falle por sí mismo).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<parameter>err</parameter>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Si este campo es diferente de null, un error ocurrido en la operación anterior.
|
|
Si este campo está establecido, será un string describiendo el error que
|
|
ocurrió.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<parameter>code</parameter>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Si ocurrión un error de base de datos, el código de error relevante será
|
|
devuelto al cliente.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<parameter>errmsg</parameter>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Este campo está establecido si algo va mal con un comando de base de datos.
|
|
Está asociado con <literal>ok</literal> igual a 0. Por ejemplo, si
|
|
se establece <literal>w</literal> y se agota el tiempo, errmsg será establecido a "timed
|
|
out waiting for slaves" y <literal>ok</literal> será 0. Si este campo
|
|
es establecido, será un string que describe el error ocurrido.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<parameter>n</parameter>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Si la última operación fue de inserción, una upsert, o una eliminación, será
|
|
devuelto el número de objetos afectados. Para operaciones de inserción, este valor
|
|
siempre es <literal>0</literal>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<parameter>wtimeout</parameter>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Si la opción anterior agota el tiempo, esperará a una réplica.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<parameter>waited</parameter>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Cuánto esperará la operación antes de agotarse el tiempo.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<parameter>wtime</parameter>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Si <literal>w</literal> fue establecido y la operación tiene éxito, cuánto toma
|
|
la réplica a los servidores de <literal>w</literal>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<parameter>upserted</parameter>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Si ocurre una upsert, este campo contendrá el nuevo campo
|
|
<literal>_id</literal> del registro. Para upserts, estará presente
|
|
este campo o <literal>updatedExisting</literal> (a menos que ocurra un
|
|
error).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<parameter>updatedExisting</parameter>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Si una upsert actualiza un elemento existente, este campo será "true". Para
|
|
upsert, estará presente este campo o 'upserted' (a menos que ocurra un
|
|
error).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="errors">
|
|
&reftitle.errors;
|
|
<para>
|
|
Lanza una <classname>MongoException</classname> si el documento insertado está
|
|
vacío o si contiene claves de longitud cero. Intentar insertar un objeto
|
|
con propiedades protegidas o privadas causará un error de clave de longitud cero.
|
|
</para>
|
|
&mongo.errors.exceptions.writeconcern;
|
|
</refsect1>
|
|
|
|
<refsect1 role="changelog">
|
|
&reftitle.changelog;
|
|
<para>
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>&Version;</entry>
|
|
<entry>&Description;</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>1.5.0</entry>
|
|
<entry>
|
|
<para>
|
|
Se añadió la opción <literal>"wTimeoutMS"</literal>, la cual remplaza a
|
|
<literal>"wtimeout"</literal>. Emite un error de nivel <constant>E_DEPRECATED</constant>
|
|
cuando se usa <literal>"wtimeout"</literal>.
|
|
</para>
|
|
<para>
|
|
Se añadió la opción <literal>"socketTimeoutMS"</literal>, la cual remplza a
|
|
<literal>"timeout"</literal>. Emite un error de nivel <constant>E_DEPRECATED</constant>
|
|
cuando se usa <literal>"timeout"</literal>.
|
|
</para>
|
|
<para>
|
|
Emite un error de nivel <constant>E_DEPRECATED</constant> al
|
|
usar <literal>"safe"</literal>.
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>1.3.4</entry>
|
|
<entry>Se añadió la opción <literal>"wtimeout"</literal>.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>1.3.0</entry>
|
|
<entry>
|
|
<para>Se añadió la opción <literal>"w"</literal>.</para>
|
|
<para>
|
|
El parámetro <parameter>options</parameter> ya no acepta un booleano
|
|
para indicar una escritura aceptada. En su lugar, ahora esto tiene que realizarse con
|
|
<literal>array('w' => 1)</literal> (El comportamiento predeterminado de
|
|
<classname>MongoClient</classname>).
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>1.2.0</entry>
|
|
<entry>Se añadió el parámetro <literal>"timeout"</literal>.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>1.0.11</entry>
|
|
<entry>
|
|
Se desconecta en errores "not master" si <literal>"safe"</literal> está establecido.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>1.0.9</entry>
|
|
<entry>
|
|
<para>
|
|
Añadida la capacidad de pasar enteros a la opción <literal>"safe"</literal>,
|
|
la cual anteriormente únicamente aceptaba booleanos.
|
|
</para>
|
|
<para>
|
|
Añadida la opción <literal>"fsync"</literal>.
|
|
</para>
|
|
<para>
|
|
Cambiado el tipo devuelto por un array que contiene información
|
|
si se utiliza la opción <literal>"safe"</literal>. De otro modo, se devuelve
|
|
un booleano como antes.
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>1.0.2</entry>
|
|
<entry>
|
|
Cambiado el segundo parámetro a un array de opciones. Antes de la versión
|
|
1.0.2, el segundo parámetro era un booleano indicando la opción
|
|
<literal>"safe"</literal>.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>1.0.1</entry>
|
|
<entry>
|
|
Lanza una <classname>MongoCursorException</classname> si la
|
|
opción <literal>"safe"</literal> está establecida y la inserción falla.
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="examples">
|
|
&reftitle.examples;
|
|
<example>
|
|
<title>Ejemplo de <function>MongoCollection::insert</function> con <literal>_id</literal></title>
|
|
<para>
|
|
Un campo <literal>_id</literal> será añadido al documento insertado si
|
|
no estuviera ya presente. Dependiendo de cómo el parámetro sea pasado, estará disponible
|
|
o no un <literal>_id</literal> generado para llamar al código.
|
|
</para>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
|
|
$m = new MongoClient();
|
|
$colección = $m->selectCollection('test', 'phpmanual');
|
|
|
|
// Si se usa un array literal, no hay forma de acceder al _id generado
|
|
$colección->insert(array('x' => 1));
|
|
|
|
// El _id está disponible en un array pasado por valor
|
|
$a = array('x' => 2);
|
|
$colección->insert($a);
|
|
var_dump($a);
|
|
|
|
// El _id no está disponible en un array pasado por referencia
|
|
$b = array('x' => 3);
|
|
$ref = &$b;
|
|
$colección->insert($ref);
|
|
var_dump($ref);
|
|
|
|
// El _id está disponible si una función envolvente no desencadena una copia durante la escritura
|
|
function insert_no_cow($colección, $documento)
|
|
{
|
|
$colección->insert($documento);
|
|
}
|
|
|
|
$c = array('x' => 4);
|
|
insert_no_cow($colección, $c);
|
|
var_dump($c);
|
|
|
|
// El _id no está disponible si una función envolvente desencadena una copia durante la escritura
|
|
function insert_cow($colección, $documento)
|
|
{
|
|
$documento['y'] = 1;
|
|
$colección->insert($documento);
|
|
}
|
|
|
|
$d = array('x' => 5);
|
|
insert_cow($colección, $d);
|
|
var_dump($d);
|
|
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
&example.outputs.similar;
|
|
<screen>
|
|
<![CDATA[
|
|
array(2) {
|
|
["x"]=>
|
|
int(2)
|
|
["_id"]=>
|
|
object(MongoId)#4 (0) {
|
|
}
|
|
}
|
|
array(1) {
|
|
["x"]=>
|
|
int(3)
|
|
}
|
|
array(2) {
|
|
["x"]=>
|
|
int(4)
|
|
["_id"]=>
|
|
object(MongoId)#5 (0) {
|
|
}
|
|
}
|
|
array(1) {
|
|
["x"]=>
|
|
int(5)
|
|
}
|
|
]]>
|
|
</screen>
|
|
</example>
|
|
|
|
<example>
|
|
<title>Ejemplo de escritura aceptada con <function>MongoCollection::insert</function></title>
|
|
<para>
|
|
Este ejemplo muestra cómo al insertar dos elementos con el mismo _id, se provoca
|
|
que se lance una excepción <classname>MongoCursorException</classname>, ya que
|
|
<parameter>w</parameter> está habilitado.
|
|
</para>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
|
|
$persona = array("nombre" => "Joe", "edad" => 20);
|
|
$colección->insert($persona);
|
|
|
|
// ahora $persona tiene un campo _id, así que si intentamos guardarlo
|
|
// de nuevo, obtendremos una excepción
|
|
try {
|
|
$collection->insert($persona, array("w" => 1));
|
|
} catch(MongoCursorException $e) {
|
|
echo "No se puede guardar dos veces la misma persona!\n";
|
|
}
|
|
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</refsect1>
|
|
|
|
<refsect1 role="seealso">
|
|
&reftitle.seealso;
|
|
<simplelist>
|
|
<member><function>MongoCollection::batchInsert</function></member>
|
|
<member><function>MongoCollection::update</function></member>
|
|
<member><function>MongoCollection::find</function></member>
|
|
<member><function>MongoCollection::remove</function></member>
|
|
<member>Documentación de MongoDB sobre <link xlink:href="&url.mongodb.dochub.insert;">insert</link>.</member>
|
|
</simplelist>
|
|
</refsect1>
|
|
|
|
</refentry>
|
|
<!-- Keep this comment at the end of the file
|
|
Local variables:
|
|
mode: sgml
|
|
sgml-omittag:t
|
|
sgml-shorttag:t
|
|
sgml-minimize-attributes:nil
|
|
sgml-always-quote-attributes:t
|
|
sgml-indent-step:1
|
|
sgml-indent-data:t
|
|
sgml-parent-document:nil
|
|
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
|
|
sgml-exposed-tags:nil
|
|
sgml-local-catalogs:nil
|
|
sgml-local-ecat-files:nil
|
|
End:
|
|
vim600: syn=xml fen fdm=syntax fdl=2 si
|
|
vim: et tw=78 syn=sgml
|
|
vi: ts=1 sw=1
|
|
-->
|