| // Licensed to the Apache Software Foundation (ASF) under one |
| // or more contributor license agreements. See the NOTICE file |
| // distributed with this work for additional information |
| // regarding copyright ownership. The ASF licenses this file |
| // to you under the Apache License, Version 2.0 (the |
| // "License"); you may not use this file except in compliance |
| // with the License. You may obtain a copy of the License at |
| // |
| // http://www.apache.org/licenses/LICENSE-2.0 |
| // |
| // Unless required by applicable law or agreed to in writing, |
| // software distributed under the License is distributed on an |
| // "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| // KIND, either express or implied. See the License for the |
| // specific language governing permissions and limitations |
| // under the License. |
| |
| [[_uv3.annotation_relation_predicates]] |
| = Annotation relation predicates |
| |
| When working with annotations, it is often necessary to express how two annotations related |
| to each other. This happens for example when using the Select framework to say "select all |
| annotations of type T that follow a given annotation X". So there are a number of possible |
| relationships which two annotations can have with each other such as "following", "preceding", |
| "being colocated", "being covered by", "covering", etc. This chapter provides specification of |
| these relationships which are also available as a set of predicate functions. The Select framework |
| is also consistent with these definitions. In order to query the CAS for annotations that exist |
| in a certain relationship to each other, it is possible to e.g. stream an entire annotation index |
| or CAS and filtering the annotations using the provided predicate functions. However, using the |
| corresponding selector functions of the Select framework is generally much faster than filtering |
| using the predicates as Select knows more efficient way of finding the starting point for a |
| particular query in the annotation index and also knows when a search can be aborted without |
| having to scan an entire index and also without missing any matches. The predicates are |
| implemented as static functions in the `org.apache.uima.cas.text.AnnotationPredicates` |
| class. |
| |
| .Annotation relation types |
| image::images/version_3_users_guide/annotation_predicates/annotation-relations-table.png[Matrix showing possible annotation relations and the cases where they apply.] |
| |
| As shown below, all of the relations can be expressed in terms of the "covered by" relation. |
| |
| .Annotation relation types |
| image::images/version_3_users_guide/annotation_predicates/annotation-relations-definition.png[Definition of the relations.] |
