FastLight Logo

FastLight Framework 2 DOCS

Documentación de querybuilder_sql

La clase QueryBuilder

Preparación de consultas SQL (BETA)

Mediante el Query Builder, podemos crear consultas SQL y ejecutarlas. Esta clase permite crear objetos QueryBuilder, trabajando con PDO y sentencias preparadas.

En la versión v2.2.0 de FastLight el QueryBuilder soporta consultas de selección, inserción, actualización y borrado sobre una única tabla. Soporta cláusulas WHERE, GROUB BY (y cálculo de totales mediante funciones de agregado), ORDER BY, LIMIT y OFFSET. Otras funcionalidades se irán añadiendo poco a poco.

Los siguientes ejemplos se muestran cómo crear consultas SQL de los tipos más comunes: SELECT, INSERT, UPDATE y DELETE. Para ver ejemplos de cómo ejecutar las consultas, visitad el ejemplo ejecución de consultas mediante el Query Builder.

El QueryBuilder de FastLight ORM se encuentra aún en desarrollo, no se debe usar más que a modo experimental y para detectar errores.

Índice

Creando objetos QueryBuilder

El constructor

Para crear instancias de QueryBuilder, podemos usar el constructor.

La conexión PDO se puede establecer o recuperar posteriormente mediante los métodos setPDO(PDO $pdo) y getPDO(). También se puede pasar en el momento de preparar la sentencia con el método prepare(?PDO $pdo) o bien cuando ejecutemos la consulta con el método get(?PDO $pdo). Estos métodos se explican en el ejemplo ejecución de consultas mediante el Query Builder.

Si tratamos de imprimir un objeto QueryBuilder o lo usamos en un contexto de sting, se mostrará la consulta SQL que generará. También se puede recuperar el SQL haciendo uso del método getSQL().

Métodos estáticos

Para facilitar la tarea de crear instancias de QueryBuilder, existen también una serie de método estáticos que realizan la misma tarea. Todos ellos retornan la instancia creada.

El parámetro $table es obligatorio, mientras que la conexión PDO es opcional.

En todos los ejemplos a continuación, se muestran las consultas SQL que generan y los bindings para la ejecución de las sentencias preparadas.

Consultas SELECT sencillas

Todos los registros, todos los campos

Las consultas de selección más básicas consisten en recuperar todos los registros y todos los campos de una tabla. Para ello tan solo hace falta crear la instancia pasándole el nombre de tabla.

Todos los registros, algunos campos

Tenemos varias opciones para indicar los campos a recuperar en la consulta de selección. Podemos usar el método field(), que recibe por parámetro el nombre del campo a recuperar o el método fields(), que permite especificar un array de nombres de campo.

Es equivalente usar varias veces el método field() o usar una vez el método fields() con varios campos.

Valores no repetidos

Para bucar valores no repetidos, podemos añadir el texto DISTINCT antes del campo.

Consultas con condiciones

Para realizar consultas con condiciones, usamos los métodos where(), whereAnd(), whereOr(), whereLike(), whereRegExp(), whereIn(), whereNotBetween(), whereNotBetween() o whereNotIn(). Es equivalente usar where() o whereAnd(). El resto de métodos forman consultas con OR, LIKE, REGEXP, BETWEEN, NOT BETWEEN, IN y NOT IN.

Es importante tener en cuenta que el método where() recibe dos parámetros:

La condición está formada por el campo, el operador y el interrogante, que es el símbolo para la posterior vinculación del parámetro.

El método whereAnd() es alias de where().

Si queremos indicar varias condiciones, pero aplicando una OR en lugar de una AND, podemos usar el método whereOr().

Hay que tener cuidado con la precedencia de los operadores lógicos puesto que el AND es prioritario, por ese motivo este método añade paréntesis alrededor de la expresión. Aún así hay que revisar bien que la estructura de la clausula WHERE sea la que pretendemos.

Las consultas que mezclan múltiples AND y OR pueden no salir como esperamos. Por ejemplo supongamos que queremos hacer (A OR B) AND C OR D, usando estos métodos obtendremos lo que se muestra en el siguiente ejemplo, que es (A OR B) AND (C OR D) y no es equivalente.

Algunos frameworks lo solucionan mediante un generador de expresiones complejo (Symfony), pero en FastLight esto aún no está contemplado. Una posible solución es realizar una vista en la BDD con la consulta deseada y realizar una consulta de selección simple sobre ella.

Para consultas con LIKE en la cláusula WHERE, podemos usar tanto el método where() en la forma en que se puede ver en el ejemplo anterior, o bien usar el método whereLike().

Si lo que queremos es hacer pattern matching mediante una expresión regular, usaremos el método whereRegExp().

Esto también se puede hacer usando el método where(), por ejemplo haciendo ->where('name REGEXP ?', '^[AB]').

Este método nos permitirá aplicar un BETWEEN para buscar valores en rangos. Se puede usar tanto para números como para fechas o strings (no tan habitual). Recordemos que los valores de los extremos están incluidos.

Este método permite buscar registros que no estén en el rango indicado. Evidentemente no aparecerán tampoco los que coincidan con los valores de los extremos.

Permite buscar coincidencias en un campo concreto a partir de una lista de valores.

No recuperará los registros con valores que coincidan con alguno de los indicados en el rango para ese campo.

Consultas con ordenación

El método order() permite indicar un criterio de ordenación. Se indica campo y sentido, aunque el sentido es opcional (ascendente por defecto).

Para múltiples criterios de ordenación, podemos invocar varias veces al método. La mayor prioridad en la ordenación es del criterio que va antes.

Límite y desplazamiento

El método limit() permite indicar tanto el LIMIT como el OFFSET para la consulta. Recibe dos números enteros como parámetro, el primero es el límite y el segundo el desplazamiento (opcional, por defecto 0).

Consultas de totales

Para realizar consultas de totales o agregados sin agrupar, podemos usar el método total().

En este ejemplo se calculan varios totales de una sola vez.

La sintaxis del método total() también permite ahorrarnos algo de código usando pipes | en lugar de invocarlo varias veces.

Evidentemente, se pueden combinar condiciones y totales sin ningún problema.

Consultas SELECT con datos agrupados

Para añadir la cláusula GROUP BY a nuestras consultas mediante las herramientas de la clase QueryBuilder, usaremos los métodos group() y groups().

El primer método permite añadir un solo campo de agrupamiento, mientras que el segundo permite añadir múltiples campos a partir de un array. Es equivalente invocar a group() varias veces o invocar a groups() una sola pasándole los mismos campos en un array.

A continuación se muestran un par de ejemplos con totales y grupos.

Consultas de inserción

Consultas INSERT

Para las consultas de inserción, podemos usar el constructor o bien el método estático QueryBuilder::insert(). Una vez instanciado el objeto, usaremos el método field() con dos parámetros para indicar los pares de campo y valor.

Consultas de actualización

Consultas UPDATE

Para las consultas de actualización, podemos usar el constructor o bien el método estático QueryBuilder::update(). Una vez instanciado el objeto, usaremos el método field() con dos parámetros para indicar los pares de campo y valor.

No olvides indicar el registro o registros a actualizar, una mala actualización puede acabar con todos los datos de la tabla.

Consultas de borrado

Consultas DELETE

Para las consultas de borrado, podemos usar el constructor o bien el método estático QueryBuilder::delete().

No olvides indicar el registro o registros a eliminar o acabaremos eliminando todos los datos de la tabla.

Consultas por partes

Creando consultas a trozos

Nada nos impide ir creando el objeto QueryBuilder a trozos, incluso recuperar el SQL de la consulta parcial.

Fin de la documentación querybuilder_sql

Lista de ejemplos.

FastLight Framework 2 DOCS, versión 2.0.10