resources/segments/search
Permits to find segments by a wide range of criteria.
- 1 URL
- 2 PARAMETERS
- 3 RESULTS
- 3.1 result.docs
- 3.2 result.users
- 3.3 result.rows
- 4 EXAMPLE
URL
(POST) /api/resources/segments/search
PARAMETERS
The message body contains a JSON object with these properties.
scope | The scope object. It delimits the total range of segments and related resources that can be queried. Example: "scope": { "type": "Project", "projectid": 1234 } | Mandatory, object |
query | The filters to apply. See chapters further down. Get segments in scope with a word in English and where the German translation has green status. Further, we want the segment context to be a "Heading" (we suppose we translate a Microsoft Word document). "query": {
"ctx": { "value": "Heading", "mode": "Prefix" },
"languages": [
{ "locs": ["en"], "text": { "value": "ministry" } },
{ "locs": ["de"], "status": { 1 } }
]
} | Optional, object? |
layout | Optional layout object. The layout presets the data and the languages you want to retrieve with the results. If not specified or null the layout is preset - see autoLayout property below. | Optional, object? |
autoLayout | If layout is not set, the system creates one depending on the values of this property:
This example returns results in 3 languages. Not setting the layoutMode requires explicitly specifying languages: {
"scope": {
"type": "Job",
"jobid": 16682,
"jobcdyt": true
},
"query": {
"languages": [
{ "locs": ["en"] },
{ "locs": ["de"] },
{ "locs": ["fr"] }
]
}
}Alternatively, this can be written more compactly: ...
"query": {
"languages": [
{ "locs": ["en", "de", "fr"] }
]
}
... | Optional, string |
usecache | Optional boolean, default is true. Set to false only if there is a possibility that user access rights have changed. False enforces the system to recalculate all access rights for the specified scope. | Optional, bool? |
Smart navigation - See explanation below | ||
previousSkip | This is the skip value of the currently shown editor page (i.e. before making this call). Use previousSkip and previousTotal when implementing translation editor interfaces. Here the user may apply a filter and navigate between pages. Consider this scenario: User sets a filter to show green status segments only. User is on page 2. Now user, sets some segments into red status and saves changes. Finally, user clicks button to move to next page (3). With smart navigation, the system will adjust the skip value to maintain it on page 2 (since page 2 now shows new segments). | Optional, int? |
previousTotal | This is the grand total amount of segments was obtained when showing the current editor page (i.e. the total known by editor before making this call) | Optional, int? |
includeRights | Default: false
Use false when possible to reduce http response size. | Optional, bool |
includeLayout | Default: false
Use false when possible to reduce http response size. | Optional, bool |
data | User custom data. You can put your own data here. It will be persisted when saving/loading queries for later reuse: resources/segments/search/profiles | Optional, string |
Paginate and sort
To paginate results, use these properties:
query.skip | Optional, default is 0. Used for pagination. Specifies the number of segments in the result set to skip. | Optional, int |
query.take | Optional, default is 20. Specifies the number of segments to retrieve. Setting take to 0 maybe useful if you only want to obtain the grand total for the filter (without fetching segments). | Optional, int |
query.sort | Optional. Default is "Natural". Specifies how results shall be sorted:
Example: "sort": "Natural" | Optional, string |
query.sortdir | Optional sort direction. Options are:
Example: "sortdir": "desc"Default sort orders:
| Optional, string? |
query.highlight | Optional, default is null. Instruction whether to highlight texts in the results that actually matched a filter in that language. Useful with terminology searches where you want to know which of the term variants in a concept actually matched the filter. Without highlighting, the system will return the concept but does not tell you which of the 3 variants is matching. Values are:
| Optional, string? |
Go to instructions
Use the goto parameter for advanced navigation:
Jump to a specific segment id. Query adjusts "skip" accordingly.
Jump to the next or previous locked text
Instructions:
Make sure to set the take parameter to specify your pagination size
Check the gotoSuccess property in the method result. If it is false then the navigation did not find anything.
The result.skip and result.take properties are the resulting pagination details.
This feature works only with certain sort values, check applicable notes below.
goto | Navigate to segment by segment ID Specify mode and segment ID as shown below. "goto": {
"mode": "SegmentId",
"sid": 2991
} | Optional, object |
Navigate to segment by sequential ID Segments of documents are assigned a sequential ID such as 1, 2, 3-1, 3-2 etc. The first part is the bee segment ID (bsid), the second part is the sub segment ID (bssid). "goto": {
"mode": "BeeSegmentId",
"bsid": 10,
"bssid": 0
}The bssid is optional. 0 denotes the first sub segment, 1 the second. In the user interfaces we display this number incremented by 1 (after all "3-1" looks better than "3-0" NOTE: This mode is available only with Job or Project scopes. | ||
Navigate to locked text Navigates to the next (next: true) or previous (next:false) locked text relative to the specified segment ID. "goto": {
"mode": "LockedYes",
"sid": 88721,
"locale": "fr",
"next": "true"
}The locale parameter is mandatory. | ||
Navigate to non-locked text Navigates to the very first unlocked segment. Here we drop the sid value and thus navigate from the start. "goto": {
"mode": "LockedNo",
"locale": "fr",
"next": "true"
}The locale parameter is mandatory. |
Filter resources and documents
The scope generally delimits the searchable resources, documents or segments. If the scope is a project then you will get the documents in this project.The following properties permit to drill down on the scope resources, documents or segments.
query.documentSets | Optional list of resources to search. A resource can be a translation memory, a term base or a project memory. See resources/documentsets to find resources and their IDs (dsid). Example: "documentSets": [ 1292, 19923 ] | Optional, int[] |
query.documents | Optional list of documents to search. With projects, a document is, well, a document being translated. With resources it groups segments added to a resource together. See resources/documents/list (post) to find documents and their IDs (did) Each element is an object with these properties:
Example: "documents": [ { "did": 77362 } ] | Optional, object[] |
query.segments | Optional list of segments to search. The segment ID is the sid property included with search results. Example: "segments": [ 992821, 992822 ] | Optional, int[] |
query.segmentsFT | Optional string with a list of segment IDs or ID ranges. Examples:
| Optional, string? |
query.segmentNumbers | Optional list of segment numbers to search. The segment number is the bsid property included with search results. It is available with projects and jobs only and is an incremental number starting at 1 (per each document). The number may contain a subsegment ID: 2-1, 2-2, 2-3 (if segment 2 is split into 3 subsegments). | Optional, string[] |
query.segmentNumbersFT | Optional string with a list of segment IDs or ID ranges. Examples:
| Optional, string? |
query.resourceTypes | Optional filter on the type of resource to search:. Options are:
Example to search resources only while excluding any documents: "resourceTypes": [ 2, 3 ] | Optional, int[] |
Filter segment level properties
The scope generally delimits the searchable resources, documents or segments. If the scope is a project then you will get the documents in this project. The following properties permit to drill down on the scope resources, documents or segments.
query.ctx | To filter by the context string of a segment. The context may be the style (such as Heading 1 in a Microsoft Word document) or a software string ID. This element is an object with the following properties: | Optional, object |
query.ctx.value | The string to search. The search is case-insensitive. | Mandatory, string |
query.ctx.mode | The search mode, any of these options. If missing then uses the "Prefix" mode. See String filter (Filter) for details. | Optional, string |
query.ctxs | To search segments by one or more context strings. The context may be the style (such as Heading 1 in a Microsoft Word document) or a software string ID. The search is case-insensitive but otherwise an exact search (not a prefix search). | Optional, string[] |
query.constraints | Optional. To find segments that have or have no size constraint (max or min length in translations). Missing or null: No filter. True: Segment must have a size constraint. False: Segment must not have a size constraint. | Optional, bool |
query.cfs | Optional filter for segment-level custom fields. A array of custom field filters. Each element filters one custom field value:
Example to find values prefixed with "Department" in custom text field #1: "cfs": [ { "id": 1, "val": "Department.*", mode: "Regex" }, { "id": 5, "val": "Priority", "phrase": true } ]When specifying multiple items, all of them must match. | Optional, object[] |
query.lbls | Optional filter for segment-level labels. A array of label filters. Each element filters one label value:
Example: "lbls": [ { "id": 1, "val": 0 }, { "id": 23, "val": 3 }, { "id": 10, "val": null } ]When specifying multiple items, all of them must match. | Optional, object[] |
query.tbx | Optional filter on term-level TBX fields. An array of TBX field and value pairs. Each array element has these properties:
Example: "tbx": [ { "id": "context", "val": "Mechanical" }, { "id": "example", "val": "stru*e", "mode": "Wildcards" } ] | Optional, object[] |
Components
These are filters specifically useful for Flex / Strings DB queries. With Flex it is possible to group strings by “components”. A component can be a code file, a screen etc.
component | To query by the optional See String filter (Filter) for details. { "component": { "value": "label*", "mode": "Wildcards" } } | object?, Optional |
components | Filter by a list of component values. Find all segments that have a component matching any list item exactly. | string[]?, Optional |
Branches
Used with Flex containers only. Segments are uniquely identified by their key (aka context) value and their branch. The parameters below allow you to filter segments by their branch.
branch | To query by the optional See String filter (Filter) for details. { "branch": { "value": "production-*", "mode": "Wildcards" } } | object?, Optional |
branches | Filter by a list of branch values. Find all segments that have a branch matching any list item exactly. | string[]?, Optional |
Job assignments
Segments can explicitly be assigned to jobs. With such workflows, you can then filter segments by jobs (see Create New Jobs). To filter segments by their assignment, see below.
query.jobIds | A list of Standard job IDs.
{ "jobIds": [1000, 1002] } | Optional, int[]? |
query.jobTextStatus | Optional status filter. The status is not a job status but a text status: Text Status (Enumeration) The system retains segments assigned to the jobs (see criteria above) and with the job's text status at the expected value. | Optional, int? |
query.jobNot | Optional boolean, default is false.
|
Copyright Wordbee - Buzzin' Outside the Box since 2008