Regex

A models.Regex holds the text of a regular expression for the SurrealDB regex kind. SurrealDB compiles a regex with the syntax of the Rust regex crate, not with Go's regexp package. The SDK therefore keeps the pattern as text and never compiles it. This page documents the type and when you can send a regex. Sending a Regex needs SurrealDB 4.0.

Package: github.com/surrealdb/surrealdb.go/v2/pkg/models

Source: pkg/models/regex.go

Definition

type Regex struct {
	Pattern string
}

Pattern is the text of the regex, without the slashes around it. The zero value is the empty pattern, which matches any text.

Matching in a query

Send a Regex as a query variable, and use the SurrealQL = operator to compare a string with it. With a regex, = checks whether the string matches the pattern:

results, err := surrealdb.Query[[]string](ctx, db,
	"SELECT VALUE name FROM person WHERE name = $pattern",
	map[string]any{"pattern": models.Regex{Pattern: "^[A-J]"}},
)

A regex that the server returns, such as one stored in a field, decodes into a Regex, including from any.

Methods

`.String()`

Returns the regex as the server writes it: the pattern between slashes, with each slash in it escaped, as in /a\/b/.

Returns: string

`.SurrealString()`

Returns the regex as a SurrealQL literal, such as /a+/. It escapes each slash that the pattern does not escape already. For the empty pattern, it writes a cast of the empty string instead, because // starts a comment in SurrealQL.

Returns: string

path := models.Regex{Pattern: "^/api/v[0-9]+/"}
fmt.Println(path.SurrealString())

Output

/^\/api\/v[0-9]+\//

Send a regex as a variable rather than writing its literal into a query.

Rust syntax and Go's regexp

The Rust syntax is close to the RE2 syntax of Go's regexp, but not the same. In Rust, \d, \w, \s and \b match Unicode text, while in Go they match ASCII only. The class set operations of Rust, such as [a-z&&[^aeiou]], mean something else in Go. regexp.Compile(r.Pattern) gives Go's reading of a pattern, which can differ from the server's.

For this reason, the SDK never converts a *regexp.Regexp into a Regex or back. Sending a regexp.Regexp or a *regexp.Regexp fails with the error cannot encode a *regexp.Regexp, as Go's regular expression syntax is not SurrealQL's: use models.Regex.

Servers before SurrealDB 4.0

Plain CBOR, which servers before 4.0 speak, has no form for a regex. Encoding a Regex for plain CBOR fails with an error that wraps constants.ErrNeedsCBOR2, and the SDK sends nothing:

Error output with SurrealDB 3.x

cborwire: a regex (CBOR tag 193) has no plain CBOR form: the value can only be sent over cbor.2

To match on an earlier server, send the pattern as a string and cast it in the query. This works on both SurrealDB 3.x and 4.0:

results, err := surrealdb.Query[bool](ctx, db, "RETURN $name = <regex>$pattern", map[string]any{
	"name":    "tobie",
	"pattern": "^[a-z]+$",
})

An HTTP connection sends plain CBOR until the server answers it in cbor.2. A Regex in the first request of a new HTTP connection therefore fails, even with SurrealDB 4.0. Connect with WithVersionCheck(true), or sign in first, so that the connection uses cbor.2 from the start.