InsertQuery, InsertBuilder, UpdateQuery, and UpdateBuilder all support assignment-like data, but there are a few different ways to express it.

This page explains the supported forms.

¶columns() with values()

This is the most explicit insert form:

use GT\SqlBuilder\InsertBuilder;

$query = new InsertBuilder();
$query->into("student")
	->columns("id", "name")
	->values(123, "'example'");

That renders an ordinary insert into ... values ... statement.

Use this form when:

• the column list and value list are already separate in your code
• you want to mirror the SQL structure closely

¶set() with an associative array

For inserts and updates, set() also accepts an associative array:

$query->set([
	"id" => 123,
	"name" => "'example'",
]);

In an insert, that becomes:

insert into student(id, name) values(123, 'example')

In an update, that becomes:

update student set id = 123, name = 'example'

¶set() with short placeholder syntax

The shorthand form is often the most convenient:

$query->set(
	":title",
	":updatedAt",
);

In an update, that becomes:

set
	title = :title,
	updatedAt = :updatedAt

In an insert, it becomes matching inferred columns and values:

(
	title,
	updatedAt
)

values (
	:title,
	:updatedAt
)

Indexed short syntax also supports positional placeholders:

• "?title" becomes title = ? in an update
• "?title" becomes column title with value ? in an insert

¶Indexed set() values must be explicit

This is not allowed:

$query->set("title");

It throws SqlBuilderException with the message:

Indexed set() values must use explicit short syntax

That rule prevents ambiguity. If a value is indexed rather than associative, the library needs to know whether it is:

• a shorthand placeholder such as :title
• or a full assignment expression such as title = trim(:title)

¶Explicit assignment expressions

You can always provide the full SQL expression yourself:

$query->set(
	"id = uuid()",
	"name = trim(:name)",
);

For inserts, the library splits these into column names and right-hand expressions.

For updates, it keeps them as assignments.

¶How scalar values are formatted

When set() receives an associative array, scalar values are formatted as SQL literals:

• strings are used as provided
• integers are rendered as numbers
• booleans are rendered as true or false

For example:

$query->set([
	"enabled" => true,
	"archived" => false,
]);

renders:

enabled = true,
archived = false

¶Prefer placeholders for external data

Even though the library can render literal values, placeholders are usually the better option for real application input:

$query->set([
	"title" => ":title",
	"updatedAt" => ":updatedAt",
]);

That keeps SQL construction and parameter binding as separate concerns.

¶A practical rule

Choose the simplest form that still makes the intent obvious:

• use columns() / values() when you already have two ordered lists
• use associative set() when you have column-to-value pairs
• use short syntax when the placeholder name should match the column name
• use explicit assignment expressions when the right-hand side is an SQL expression

---

Next, we will look at nesting queries and reusing them in Subqueries and composition.