FQL v4 will be decommissioned on June 30, 2025. Ensure that you complete your migration from FQL v4 to FQL v10 by that date.

Fauna accounts created after August 21, 2024 must use FQL v10. These accounts will not be able to run FQL v4 queries or access the v4 Dashboard.

For more details, see the v4 EOL announcement and migration guide. Contact support@fauna.com with any questions.

`FindStrRegex`

This reference topic applies to FQL v4. Go to this page for the latest FQL v10 reference topics.

FindStrRegex( value, find, [start], [numResults] )

find_str_regex( value, find, [start], [numResults] )

FindStrRegex( value, find, [start], [numResults] )

FindStrRegex( value, find, [start], [numResults] )

FindStrRegex( value, find, [start], [numResults] )

FindStrRegex( value, find, [start], [numResults] )

Description

The FindStrRegex function returns an array of up to 1,024 objects that describe where the pattern is found in the search string.

Parameters

Parameter Type Definition and Requirements

value

String

The string to search in.

find

String

The Java-compatible regular expression pattern to find in the value string.

start

Integer

Optional - The offset into the search string in characters of where the search should start. The default value, if omitted, is 0 code points. The first position in the string is 0. If the value is less than 0, then start is ignored.

Although we mention characters, technically, we are talking about code points. In Unicode, a code point is usually, but not always, a character. Code points can sometimes represent single characters, but can also represent formatting and other non-alphanumeric characters.

For example, the character é can be the single character "e" that includes an acute accent (U+00E9), or it could be displayed as a single character but be composed of an "e" (U+0065) and a "combining" acute accent (U+0301). Visually, you cannot distinguish between the two.

numResults

Integer

Optional - The number of matches to find in the search string. The default is 1,024 and the maximum is 1,024.

Returns

An array of objects where each object contains the details of a match, including the start position, end position, and the sub-string that was matched.

Examples

The following query searches the string ABC abc ABC for the pattern [Bb], which matches the letter B or the letter b. The result is an array of the three matches that exist, with each match reporting the start and end positions of the match, and the actual sub-string that matched:

client.query(
  q.FindStrRegex('ABC abc ABC', '[Bb]')
)
.then((ret) => console.log(ret))
.catch((err) => console.error(
  'Error: [%s] %s: %s',
  err.name,
  err.message,
  err.errors()[0].description,
))

[
  { start: 1, end: 1, data: 'B' },
  { start: 5, end: 5, data: 'b' },
  { start: 9, end: 9, data: 'B' }
]

result = client.query(
  q.find_str_regex("ABC abc ABC", "[Bb]")
)
print(result)

[{'start': 1, 'end': 1, 'data': 'B'}, {'start': 5, 'end': 5, 'data': 'b'}, {'start': 9, 'end': 9, 'data': 'B'}]

result, err := client.Query(
	f.FindStrRegex("ABC abc ABC", "[Bb]"))

if err != nil {
	fmt.Fprintln(os.Stderr, err)
} else {
	fmt.Println(result)
}

[map[data:B end:1 start:1] map[data:b end:5 start:5] map[data:B end:9 start:9]]

try
{
    Value result = await client.Query(
        FindStrRegex("ABC abc ABC", "[Bb]")
    );

    Console.WriteLine(result);
}
catch (Exception e)
{
    Console.WriteLine($"ERROR: {e.Message}");
}

Arr(ObjectV(start: LongV(1),end: LongV(1),data: StringV(B)), ObjectV(start: LongV(5),end: LongV(5),data: StringV(b)), ObjectV(start: LongV(9),end: LongV(9),data: StringV(B)))

System.out.println(
    client.query(
        FindStrRegex("ABC abc ABC", "[Bb]")
    ).get());

[{start: 1, end: 1, data: "B"}, {start: 5, end: 5, data: "b"}, {start: 9, end: 9, data: "B"}]

FindStrRegex('ABC abc ABC', '[Bb]')

[
  { start: 1, end: 1, data: 'B' },
  { start: 5, end: 5, data: 'b' },
  { start: 9, end: 9, data: 'B' }
]

Query metrics:

bytesIn: 47
bytesOut: 107
computeOps: 1
readOps: 0
writeOps: 0
readBytes: 0
writeBytes: 0
queryTime: 3ms
retries: 0

The following query uses the same value string and find pattern as the previous example, but it also specifies a start position. The start position is far enough into the value string that there are only two matches in the result:

client.query(
  q.FindStrRegex('ABC abc ABC', '[Bb]', 3)
)
.then((ret) => console.log(ret))
.catch((err) => console.error(
  'Error: [%s] %s: %s',
  err.name,
  err.message,
  err.errors()[0].description,
))

[ { start: 5, end: 5, data: 'b' }, { start: 9, end: 9, data: 'B' } ]

result = client.query(
  q.find_str_regex("ABC abc ABC", "[Bb]", 5)
)
print(result)

[{'start': 5, 'end': 5, 'data': 'b'}, {'start': 9, 'end': 9, 'data': 'B'}]

result, err := client.Query(
	f.FindStrRegex("ABC abc ABC", "[Bb]", f.Start(5)))

if err != nil {
	fmt.Fprintln(os.Stderr, err)
} else {
	fmt.Println(result)
}

[map[data:b end:5 start:5] map[data:B end:9 start:9]]

try
{
    Value result = await client.Query(
        FindStrRegex("ABC abc ABC", "[Bb]", 5)
    );

    Console.WriteLine(result);
}
catch (Exception e)
{
    Console.WriteLine($"ERROR: {e.Message}");
}

Arr(ObjectV(start: LongV(5),end: LongV(5),data: StringV(b)), ObjectV(start: LongV(9),end: LongV(9),data: StringV(B)))

System.out.println(
    client.query(
        FindStrRegex("ABC abc ABC", "[Bb]", 5)
    ).get());

[{start: 5, end: 5, data: "b"}, {start: 9, end: 9, data: "B"}]

FindStrRegex('ABC abc ABC', '[Bb]', 3)

[ { start: 5, end: 5, data: 'b' }, { start: 9, end: 9, data: 'B' } ]

Query metrics:

bytesIn: 57
bytesOut: 76
computeOps: 1
readOps: 0
writeOps: 0
readBytes: 0
writeBytes: 0
queryTime: 1ms
retries: 0

The following query uses the same value string, find pattern, and start position as the previous example, but it also specifies a numResults limit. The limit restricts the number of results to one:

client.query(
  q.FindStrRegex('ABC abc ABC', '[Bb]', 3, 1)
)
.then((ret) => console.log(ret))
.catch((err) => console.error(
  'Error: [%s] %s: %s',
  err.name,
  err.message,
  err.errors()[0].description,
))

[ { start: 5, end: 5, data: 'b' } ]

result = client.query(
  q.find_str_regex("ABC abc ABC", "[Bb]", 5, 1)
)
print(result)

[{'start': 5, 'end': 5, 'data': 'b'}]

result, err := client.Query(
	f.FindStrRegex("ABC abc ABC", "[Bb]", f.Start(5), f.NumResults(1)))

if err != nil {
	fmt.Fprintln(os.Stderr, err)
} else {
	fmt.Println(result)
}

[map[data:b end:5 start:5]]

try
{
    Value result = await client.Query(
        FindStrRegex("ABC abc ABC", "[Bb]", 5, 1)
    );

    Console.WriteLine(result);
}
catch (Exception e)
{
    Console.WriteLine($"ERROR: {e.Message}");
}

Arr(ObjectV(start: LongV(5),end: LongV(5),data: StringV(b)))

System.out.println(
    client.query(
        FindStrRegex("ABC abc ABC", "[Bb]", 5, 1)
    ).get());

[{start: 5, end: 5, data: "b"}]

FindStrRegex('ABC abc ABC', '[Bb]', 3, 1)

[ { start: 5, end: 5, data: 'b' } ]

Query metrics:

bytesIn: 73
bytesOut: 45
computeOps: 1
readOps: 0
writeOps: 0
readBytes: 0
writeBytes: 0
queryTime: 3ms
retries: 0

Is this article helpful?

Tell Fauna how the article can be improved:
Visit Fauna's forums or email docs@fauna.com

Thank you for your feedback!