queryapi

Traits offering parts of a taxonomy query API. They can be assembled into "taxonomy classes". There are purely abstract query API traits, and partial implementations of those traits.

Examples of such traits are traits for querying schema content, for querying inter-concept relationships, for querying dimensional relationships in particular, etc. These traits combined form the eu.cdevreeze.tqa.base.queryapi.TaxonomyApi query API. The partial implementations combined form the eu.cdevreeze.tqa.base.queryapi.TaxonomyLike trait, which implements most of the TaxonomyApi query API.

Most query API methods are quite forgiving when the taxonomy is incomplete or incorrect. They just return the queried data to the extent that it is found. Only the getXXX methods that expect precisely one result will throw an exception if no (single) result is found.

Ideally, the taxonomy query API is very easy to use for XBRL taxonomy scripting tasks in a Scala REPL. It must also be easy to mix taxonomy query API traits, and to compose taxonomy implementations that know about specific relationship types (such as in formulas or tables), or that store specific data that is queried quite often.

TQA (except the "richtaxonomy" namespace) has no knowledge about XPath, so any XPath in the taxonomy is just text, as far as TQA is concerned.

This package unidirectionally depends on the eu.cdevreeze.tqa.base.relationship and eu.cdevreeze.tqa.base.dom packages.

Usage

In the following examples, assume that we have a taxonomy of type eu.cdevreeze.tqa.base.queryapi.TaxonomyApi, for example a eu.cdevreeze.tqa.base.taxonomy.BasicTaxonomy. It may or may not be closed under "DTS discovery rules". The examples show how the taxonomy query API, along with the types in packages eu.cdevreeze.tqa.base.relationship and eu.cdevreeze.tqa.base.dom can be used to query XBRL taxonomies.

Suppose we want to query the taxonomy for all English verbose concept labels, grouped by the concept target EName. Note that the "target EName" of a concept declaration is the name attribute along with the target namespace of the schema, as yaidom EName. Here is how we can get the concept labels:

import scala.reflect.classTag
import eu.cdevreeze.yaidom.core.EName
import eu.cdevreeze.tqa.base.relationship.ConceptLabelRelationship

val concepts: Set[EName] =
  taxonomy.findAllConceptDeclarations.map(_.targetEName).toSet

val conceptLabelRelationshipsByConceptEName = (concepts.toIndexedSeq map { conceptEName =>
  val conceptLabelRels =
    taxonomy.filterOutgoingConceptLabelRelationships(conceptEName) { rel =>

      rel.language == "en" && rel.resourceRole == "http://www.xbrl.org/2003/role/verboseLabel"
    }

  (conceptEName -> conceptLabelRels)
}).toMap

val verboseEnConceptLabels: Map[EName, Set[String]] =
  conceptLabelRelationshipsByConceptEName mapValues { rels =>
    rels.map(_.labelText).toSet
  }

In the example above, each concept should have at most one English verbose label, unless relationship prohibition/overriding is used. Validating this is an exercise for the reader, as they say. Note that in the example above, we mainly used the following knowledge about XBRL taxonomies: we get concept-labels by querying for concept-label relationships, which are standard relationships.

Now suppose we want to find all English terse concept labels, grouped by the concept target EName, but only for concrete primary items. So we exclude abstract concepts, tuples, hypercubes and dimensions. Here is how:

val concepts: Set[EName] =
  taxonomy.filterPrimaryItemDeclarations(_.isConcrete).map(_.targetEName).toSet

val conceptLabelRelationshipsByConceptEName = (concepts.toIndexedSeq map { conceptEName =>
  val conceptLabelRels =
    taxonomy.filterOutgoingConceptLabelRelationships(conceptEName) { rel =>

      rel.language == "en" && rel.resourceRole == "http://www.xbrl.org/2003/role/terseLabel"
    }

  (conceptEName -> conceptLabelRels)
}).toMap

val terseEnConceptLabels: Map[EName, Set[String]] =
  conceptLabelRelationshipsByConceptEName mapValues { rels =>
    rels.map(_.labelText).toSet
  }

To simulate how TQA retrieves concrete primary item declarations, we could write more verbosely:

import eu.cdevreeze.tqa.base.dom.ConceptDeclaration
import eu.cdevreeze.tqa.base.dom.PrimaryItemDeclaration

val substitutionGroupMap = taxonomy.substitutionGroupMap
val conceptDeclarationBuilder = new ConceptDeclaration.Builder(substitutionGroupMap)

val concepts: Set[EName] =
  taxonomy.filterGlobalElementDeclarations(_.isConcrete).
    flatMap(decl => conceptDeclarationBuilder.optConceptDeclaration(decl)).
    collect({ case decl: PrimaryItemDeclaration => decl }).map(_.targetEName).toSet

To simulate how TQA filters the concept label relationships we are interested in, we could write more verbosely:

import eu.cdevreeze.tqa.ENames

// Falling back to more general method filterOutgoingStandardRelationshipsOfType

val conceptLabelRelationshipsByConceptEName = (concepts.toIndexedSeq map { conceptEName =>
  val conceptLabelRels =
    taxonomy.filterOutgoingStandardRelationshipsOfType(
      conceptEName,
      classTag[ConceptLabelRelationship]) { rel =>

      rel.resolvedTo.resolvedElem.attribute(ENames.XmlLangEName) == "en" &&
        rel.resolvedTo.resolvedElem.attributeOption(ENames.XLinkRoleEName).contains("http://www.xbrl.org/2003/role/terseLabel")
    }

  (conceptEName -> conceptLabelRels)
}).toMap

val terseEnConceptLabels: Map[EName, Set[String]] =
  conceptLabelRelationshipsByConceptEName mapValues { rels =>
    rels.map(_.resolvedTo.resolvedElem.text).toSet
  }

Suppose we want to query the taxonomy for the parent-child presentation hierarchies in some custom ELR (extended link role). Note that the result can come from multiple linkbase documents, and TQA takes care of that if we query for parent-child relationships instead of querying for the underlying XLink presentation arcs. Here is how we get the top 2 levels:

import scala.collection.immutable
import eu.cdevreeze.tqa.base.relationship.ParentChildRelationship

val parentChildRelationships =
  taxonomy.filterParentChildRelationships(_.elr == customElr)

val topLevelConcepts: Set[EName] =
  parentChildRelationships.map(_.sourceConceptEName).toSet.diff(
    parentChildRelationships.map(_.targetConceptEName).toSet)

val topLevelParentChildren: Map[EName, immutable.IndexedSeq[EName]] =
  (topLevelConcepts.toIndexedSeq map { conceptEName =>
    val parentChildren =
      taxonomy.filterOutgoingParentChildRelationships(conceptEName)(_.elr == customElr)

    val childENames = parentChildren.sortBy(_.order).map(_.targetConceptEName)

    (conceptEName -> childENames)
  }).toMap

These examples only scratch the surface of what is possible. Dimensional relationship queries are typically more interesting than the examples above, for example. See eu.cdevreeze.tqa.base.queryapi.DimensionalRelationshipContainerApi for the dimensional query API that is part of eu.cdevreeze.tqa.base.queryapi.TaxonomyApi.

Notes on performance

The performance characteristics of the eu.cdevreeze.tqa.base.queryapi.TaxonomyApi trait and its implementations partially depend on the concrete "taxonomy" class used. Still we can say in general that:

Querying for concept declarations and schema components in general, based on the "target EName", is very fast.
Other than that, querying for concept declarations and schema components in general is slow.
Querying for outgoing and incoming standard relationships, given a concept EName, is very fast.
Other than that, querying for relationships is in general slow.

In other words, in "inner loops", do not query for taxonomy content other than querying based on specific concept ENames! Note that in the examples above, we started with a slow query, and used fast queries based on concept ENames after that. Keep in mind that in taxonomies with millions of relationships the slow queries may have to process collections of all those relationships.

Linear Supertypes

AnyRef, Any

Type Members

trait ConceptLabelRelationshipContainerApi extends AnyRef

Purely abstract trait offering a concept-label relationship query API.
Purely abstract trait offering a concept-label relationship query API.
Implementations may be strict or lenient in enforced requirements on the relationship container.
trait ConceptLabelRelationshipContainerLike extends ConceptLabelRelationshipContainerApi

Partial implementation of ConceptLabelRelationshipContainerApi.
trait ConceptReferenceRelationshipContainerApi extends AnyRef

Purely abstract trait offering a concept-reference relationship query API.
Purely abstract trait offering a concept-reference relationship query API.
Implementations may be strict or lenient in enforced requirements on the relationship container.
trait ConceptReferenceRelationshipContainerLike extends ConceptReferenceRelationshipContainerApi

Partial implementation of ConceptReferenceRelationshipContainerApi.
trait DimensionalRelationshipContainerApi extends AnyRef

Purely abstract trait offering a dimensional relationship query API.
Purely abstract trait offering a dimensional relationship query API.
Implementations may be strict or lenient in enforced requirements on the relationship container.
trait DimensionalRelationshipContainerLike extends DimensionalRelationshipContainerApi

Partial implementation of DimensionalRelationshipContainerApi.
type DomainAwareRelationshipPath = InterConceptRelationshipPath[DomainAwareRelationship]
type DomainMemberRelationshipPath = InterConceptRelationshipPath[DomainMemberRelationship]
trait ElementLabelRelationshipContainerApi extends AnyRef

Purely abstract trait offering an element-label relationship query API.
Purely abstract trait offering an element-label relationship query API.
Implementations may be strict or lenient in enforced requirements on the relationship container.
trait ElementLabelRelationshipContainerLike extends ElementLabelRelationshipContainerApi

Partial implementation of ElementLabelRelationshipContainerApi.
trait ElementReferenceRelationshipContainerApi extends AnyRef

Purely abstract trait offering an element-reference relationship query API.
Purely abstract trait offering an element-reference relationship query API.
Implementations may be strict or lenient in enforced requirements on the relationship container.
trait ElementReferenceRelationshipContainerLike extends ElementReferenceRelationshipContainerApi

Partial implementation of ElementReferenceRelationshipContainerApi.
trait InterConceptRelationshipContainerApi extends AnyRef

Purely abstract trait offering an inter-concept relationship query API.
Purely abstract trait offering an inter-concept relationship query API.
Implementations should make sure that looking up relationships by source (or target) EName is fast.
Implementations may be strict or lenient in enforced requirements on the relationship container.
For some of the graph theory terms used, see http://artint.info/html/ArtInt_50.html.
trait InterConceptRelationshipContainerLike extends InterConceptRelationshipContainerApi

Partial implementation of InterConceptRelationshipContainerApi.
trait NonStandardRelationshipContainerApi extends AnyRef

Purely abstract trait offering a non-standard relationship query API.
Purely abstract trait offering a non-standard relationship query API.
Implementations should make sure that looking up relationships by source XML fragment key is fast.
Implementations may be strict or lenient in enforced requirements on the relationship container.
For some of the graph theory terms used, see http://artint.info/html/ArtInt_50.html.
trait NonStandardRelationshipContainerLike extends NonStandardRelationshipContainerApi

Partial implementation of NonStandardRelationshipContainerApi.
type ParentChildRelationshipPath = InterConceptRelationshipPath[ParentChildRelationship]
trait PresentationRelationshipContainerApi extends AnyRef

Purely abstract trait offering a presentation relationship query API.
Purely abstract trait offering a presentation relationship query API.
Implementations may be strict or lenient in enforced requirements on the relationship container.
trait PresentationRelationshipContainerLike extends PresentationRelationshipContainerApi

Partial implementation of PresentationRelationshipContainerApi.
trait SchemaApi extends AnyRef

Purely abstract trait offering a schema API.
Purely abstract trait offering a schema API. It offers methods to regard a taxonomy as a collection of schema documents, without any knowledge about XBRL in particular.
Implementations should make sure that looking up schema content by EName is fast. Lookup up global element declarations by URI must also be fast.
Implementations may be strict or lenient in enforced requirements on the schema. For example, implementations are free to check or ignore that within a "schema" "target" expanded names of global element declarations, type definitions etc. must be unique.
Only methods for querying "global" schema content are offered. The returned objects themselves can be used to query for nested content.
Finder methods for schema root elements and their (expected) children (like global element declarations, named type definitions etc.) are free to stop searching beyond topmost found elements. Hence, in schema-invalid taxonomies, it is possible that these finder methods do not find all elements of the expected type.
trait SchemaLike extends SchemaApi

Partial implementation of trait SchemaApi.
trait StandardRelationshipContainerApi extends AnyRef

Purely abstract trait offering a standard relationship query API.
Purely abstract trait offering a standard relationship query API.
Implementations should make sure that looking up relationships by source EName is fast.
Implementations may be strict or lenient in enforced requirements on the relationship container.
For some of the graph theory terms used, see http://artint.info/html/ArtInt_50.html.
trait StandardRelationshipContainerLike extends StandardRelationshipContainerApi

Partial implementation of StandardRelationshipContainerApi.
trait TaxonomyApi extends TaxonomySchemaApi with StandardRelationshipContainerApi with NonStandardRelationshipContainerApi with InterConceptRelationshipContainerApi with PresentationRelationshipContainerApi with ConceptLabelRelationshipContainerApi with ConceptReferenceRelationshipContainerApi with ElementLabelRelationshipContainerApi with ElementReferenceRelationshipContainerApi with DimensionalRelationshipContainerApi

Purely abstract trait offering a taxonomy query API.
Purely abstract trait offering a taxonomy query API. It combines several other purely abstract query API traits. The query API concerns the taxonomy as taxonomy schema, and as container of relationships, standard relationships, inter-concept relationships and dimensional relationships.
trait TaxonomyLike extends TaxonomyApi with TaxonomySchemaLike with StandardRelationshipContainerLike with NonStandardRelationshipContainerLike with InterConceptRelationshipContainerLike with PresentationRelationshipContainerLike with ConceptLabelRelationshipContainerLike with ConceptReferenceRelationshipContainerLike with ElementLabelRelationshipContainerLike with ElementReferenceRelationshipContainerLike with DimensionalRelationshipContainerLike

Partial implementation of TaxonomyApi, formed by combining partial implementations of other query API traits.
trait TaxonomySchemaApi extends SchemaApi

Purely abstract trait offering a dimensionally-aware XBRL taxonomy schema API.
Purely abstract trait offering a dimensionally-aware XBRL taxonomy schema API.
See super-type SchemaApi for more information.
Primary item declarations are concept declarations that are neither hypercubes nor dimensions, regardless of whether they are used as primary items or domain members!
trait TaxonomySchemaLike extends TaxonomySchemaApi with SchemaLike

Partial implementation of trait TaxonomySchemaApi.

package queryapi

Usage

Notes on performance

Type Members

trait ConceptLabelRelationshipContainerApi extends AnyRef

trait ConceptLabelRelationshipContainerLike extends ConceptLabelRelationshipContainerApi

trait ConceptReferenceRelationshipContainerApi extends AnyRef

trait ConceptReferenceRelationshipContainerLike extends ConceptReferenceRelationshipContainerApi

trait DimensionalRelationshipContainerApi extends AnyRef

trait DimensionalRelationshipContainerLike extends DimensionalRelationshipContainerApi

type DomainAwareRelationshipPath = InterConceptRelationshipPath[DomainAwareRelationship]

type DomainMemberRelationshipPath = InterConceptRelationshipPath[DomainMemberRelationship]

trait ElementLabelRelationshipContainerApi extends AnyRef

trait ElementLabelRelationshipContainerLike extends ElementLabelRelationshipContainerApi

trait ElementReferenceRelationshipContainerApi extends AnyRef

trait ElementReferenceRelationshipContainerLike extends ElementReferenceRelationshipContainerApi

trait InterConceptRelationshipContainerApi extends AnyRef

trait InterConceptRelationshipContainerLike extends InterConceptRelationshipContainerApi

trait NonStandardRelationshipContainerApi extends AnyRef

trait NonStandardRelationshipContainerLike extends NonStandardRelationshipContainerApi

type ParentChildRelationshipPath = InterConceptRelationshipPath[ParentChildRelationship]

trait PresentationRelationshipContainerApi extends AnyRef

trait PresentationRelationshipContainerLike extends PresentationRelationshipContainerApi

trait SchemaApi extends AnyRef

trait SchemaLike extends SchemaApi

trait StandardRelationshipContainerApi extends AnyRef

trait StandardRelationshipContainerLike extends StandardRelationshipContainerApi

trait TaxonomySchemaApi extends SchemaApi

trait TaxonomySchemaLike extends TaxonomySchemaApi with SchemaLike

Inherited from AnyRef

Inherited from Any

Ungrouped