Opik Query Language (OQL)

1
// Exact match
2
'name = "greeting-prompt"';
3
4
// Not equal
5
'name != "old-prompt"';
6
7
// Contains substring (case-insensitive)
8
'name contains "greeting"';
9
10
// Does not contain substring
11
'name not_contains "deprecated"';
12
13
// Starts with prefix
14
'name starts_with "prod-"';
15
16
// Ends with suffix
17
'name ends_with "-v2"';

1
// Greater than (alphabetical for strings, numeric for numbers)
2
'name > "m"'; // Names starting with n-z
3
'duration > 300'; // Threads longer than 300 seconds
4
5
// Less than (alphabetical for strings, numeric for numbers)
6
'name < "m"'; // Names starting with a-l
7
'number_of_messages < 5'; // Threads with fewer than 5 messages
8
9
// Greater than or equal
10
'feedback_scores.quality >= 0.8';
11
12
// Less than or equal
13
'duration <= 600';

1
// Equality
2
'number_of_messages = 3';
3
4
// Not equal
5
'duration != 0';
6
7
// Check if field is empty
8
'feedback_scores.quality is_empty';
9
10
// Check if field is not empty
11
'feedback_scores.quality is_not_empty';

1
// Use ISO 8601 format for dates
2
'start_time >= "2024-01-01T00:00:00Z"';
3
'end_time < "2024-12-31T23:59:59Z"';

1
// Exact match
2
'environment = "production"';
3
4
// Not equal
5
'environment != "development"';
6
7
// Match any of a set of values
8
'environment in ("production", "staging")';
9
10
// Exclude a set of values
11
'environment not_in ("development", "local")';

1
// Check if list contains value
2
'tags contains "production"';
3
4
// Check if list does not contain value
5
'tags not_contains "experimental"';

1
// Multiple conditions with AND
2
'tags contains "production" AND name contains "greeting" AND created_by = "user@example.com"';
3
4
// Complex multi-field filtering
5
'name starts_with "prod-" AND tags contains "stable" AND name not_contains "deprecated"';

1
import { Opik } from "opik";
2
3
const client = new Opik();
4
5
// Filter by single tag
6
const prod = await client.searchPrompts('tags contains "production"');
7
8
// Combine name pattern and tag
9
const approved = await client.searchPrompts(
10
  'name starts_with "prod-" AND tags contains "qa-approved"'
11
);
12
13
// Multiple conditions
14
const results = await client.searchPrompts(
15
  'created_by = "user@example.com" AND tags contains "production" AND name not_contains "deprecated"'
16
);

1
import { Opik } from "opik";
2
3
const client = new Opik();
4
5
// Filter by status
6
const activeThreads = await client.searchThreads({
7
  projectName: "my-project",
8
  filterString: 'status = "active"'
9
});
10
11
// Filter by duration and message count
12
const longConversations = await client.searchThreads({
13
  projectName: "my-project",
14
  filterString: 'duration > 300 AND number_of_messages >= 5'
15
});
16
17
// Filter by feedback score
18
const highQualityThreads = await client.searchThreads({
19
  projectName: "my-project",
20
  filterString: 'feedback_scores.quality > 0.8'
21
});
22
23
// Filter by empty feedback score
24
const unratedThreads = await client.searchThreads({
25
  projectName: "my-project",
26
  filterString: 'feedback_scores.quality is_empty'
27
});
28
29
// Filter by environment
30
const prodThreads = await client.searchThreads({
31
  projectName: "my-project",
32
  filterString: 'environment = "production"'
33
});
34
35
// Filter by multiple environments
36
const stagingOrProdThreads = await client.searchThreads({
37
  projectName: "my-project",
38
  filterString: 'environment in ("production", "staging")'
39
});
40
41
// Filter by tags and metadata
42
const importantProdThreads = await client.searchThreads({
43
  projectName: "my-project",
44
  filterString: 'tags contains "important" AND metadata.environment = "production"'
45
});
46
47
// Filter by date range
48
const recentThreads = await client.searchThreads({
49
  projectName: "my-project",
50
  filterString: 'start_time >= "2024-01-01T00:00:00Z"'
51
});

1
import { Opik } from "opik";
2
3
const client = new Opik();
4
5
// Filter by metadata
6
const traces = await client.searchTraces({
7
  projectName: "my-project",
8
  filterString: 'metadata.model = "gpt-5"'
9
});
10
11
// Filter by feedback scores
12
const goodTraces = await client.searchTraces({
13
  projectName: "my-project",
14
  filterString: 'feedback_scores.accuracy > 0.9'
15
});
16
17
// Filter by environment
18
const prodTraces = await client.searchTraces({
19
  projectName: "my-project",
20
  filterString: 'environment = "production"'
21
});
22
23
// Combine environment with other filters
24
const goodProdTraces = await client.searchTraces({
25
  projectName: "my-project",
26
  filterString: 'environment = "production" AND feedback_scores.accuracy > 0.9'
27
});

1
// ✅ Correct - double quotes around values
2
await client.searchPrompts('name = "my-prompt"');
3
await client.searchPrompts('tags contains "production"');
4
5
// ❌ Incorrect - missing quotes
6
await client.searchPrompts("name = my-prompt"); // Will fail
7
8
// ❌ Incorrect - single quotes
9
await client.searchPrompts("name = 'my-prompt'"); // Will fail

1
try {
2
  const results = await client.searchPrompts("invalid syntax ===");
3
} catch (error) {
4
  console.error("Invalid OQL syntax:", error.message);
5
}