Conditional markers

Named marker

static readonly QueryCommand SearchAlbums = new("SELECT AlbumId AS Id, Title FROM albums WHERE /*ByArtist*/ ArtistId = @artistId");

var builder = SearchAlbums.StartBuilder();
builder.Use("ByArtist");
builder.Use("@artistId", 7);

List<Album> albums = builder.Query<List<Album>>(cnn);
// SELECT AlbumId AS Id, Title FROM albums WHERE ArtistId = @artistId

Without the marker value, its SQL is absent.

List<Album> albums = SearchAlbums.Query<List<Album>>(cnn);
// SELECT AlbumId AS Id, Title FROM albums

Marker tied to parameter presence

static readonly QueryCommand SearchAlbums = new("SELECT AlbumId AS Id, Title FROM albums WHERE /*@artistId*/ ArtistId = @artistId");

List<Album> albums = SearchAlbums.Query<List<Album>>(cnn, new { artistId = 7 });

The marker follows the presence of artistId.

Boolean member to marker

public sealed class AlbumFilter
{
    [ForBoolCond]
    public bool OnlyReleased { get; init; }
}

static readonly QueryCommand SearchAlbums = new("SELECT AlbumId AS Id, Title FROM albums WHERE /*OnlyReleased*/ ReleaseYear IS NOT NULL");

List<Album> albums = SearchAlbums.Query<List<Album>>(cnn, new AlbumFilter { OnlyReleased = true });

Several markers can be attached to one parameter source.

[UsesBoolConds("IncludeYear", "IncludeArtist")]
public sealed class AlbumFilter
{
    public bool IncludeDetails { get; init; }
}

One term inside parentheses

SELECT AlbumId AS Id, Title FROM albums WHERE (/*ByTitle*/ Title = @title OR IsFeatured = 1)

When ByTitle is absent, IsFeatured = 1 remains.

Larger SQL section

SELECT a.AlbumId AS Id, a.Title FROM albums a /*WithArtist*/ JOIN artists ar ON ar.ArtistId = a.ArtistId

The marker owns the removable JOIN section.

Marker logic

WHERE /*A*//*B*/ IsPublished = 1
WHERE /*A&B*/ IsPublished = 1
WHERE /*A|B*/ IsPublished = 1
WHERE /*!All*/ IsPublished = 1

Adjacent markers are an implicit AND. Explicit expressions support &, |, and ! and are evaluated from left to right.

/*A|B&C*/

(A OR B) AND C

Marker owned separator

SELECT AlbumId, Title FROM albums ORDER BY /*Title*/ Title&, /*Year*/ ReleaseYear&, AlbumId

The owned separators disappear with their optional entries.

Cheat sheet