Relations: The Graph Database Layer of Qbix Streams

The Qbix Platform treats every stream as a node in a graph. Relations between streams form the edges of this graph, enabling developers to build categories, indexes, playlists, threads, memberships, gamification mechanics, recommendations, and arbitrary higher-level structures. All of this is powered by two-directional, typed, weighted, queryable relations.

For a high-level overview of how Qbix Streams act as a full graph database, see:
Qbix Streams as a Graph Database .

Directional Relations

Each relation connects two streams in a specific direction:

[fromPublisherId/fromStreamName]
   --(type, weight, extra)-->
[toPublisherId/toStreamName]

The type determines the purpose of the relation – such as category, photo, Streams/participating, featured, or any custom value you define. The weight controls ordering, and the extra field stores arbitrary metadata for the edge.

Bidirectional Indexing

Every relation is stored twice for fast lookups:

• RelatedTo: find items related to a given category
• RelatedFrom: find categories a given item is related from

Both tables are indexed, allowing efficient O(log N) queries from either side without expensive graph traversal.

Relations as a Graph Database

Relations form a directed, typed, weighted multigraph. Developers can:

• filter by relation type
• filter by min/max weight
• limit, offset, and paginate results
• search by prefixes of stream names
• randomize ordering or insert at arbitrary weight positions
• use template prefixes (ending with "/") to build hierarchies

This allows Qbix apps to support complex structures such as threaded discussions, playlists, topic graphs, event-attendee connections, and dynamic content indexes.

The Streams::related() Function

The primary way to retrieve relations is:

list($relations, $streams, $stream) = Streams::related(
	$asUserId,
	$publisherId,
	$streamName,
	$isCategory,
	$options
);

The $isCategory flag determines whether to fetch streams related to the category or fetch categories related from the stream. Options let you filter by type, prefix, weight range, and even sort randomly.

Adding Relations: relate()

You can relate streams in either direction using:

Streams::relate(
	$asUserId,
	$toPublisherId,
	$toStreamName,
	$type,
	$fromPublisherId,
	$fromStreamName,
	$options
);

The system stores both directions, posts related-to and related-from messages, updates aggregate totals, and optionally inherits access from the related category.

Weights can be specified explicitly, incremented from the maximum, or computed from relations already present.

Removing Relations: unrelate()

To remove a relation:

Streams::unrelate(
	$asUserId,
	$toPublisherId,
	$toStreamName,
	$type,
	$fromPublisherId,
	$fromStreamName
);

This removes both entries, adjusts weights as needed, and posts the appropriate update messages.

Updating Relations

The platform provides:

• updateRelations() – bulk updates
• updateRelation() – single-edge updates

Both support updating weights, shifting neighbors, and modifying the extra metadata.

Randomized Insertion and Consumption

Several helper functions support gamified or randomized use cases:

• insertRandomly() – insert a relation in a random position
• removeInsertedRandomly() – remove while maintaining consistency
• consume() – treat relations as a consumable ordered list

Relation Metadata ("Extras")

Each relation includes an extra field – an arbitrary JSON object. Common uses include scores, badges, configuration, or extended display options.

Utility methods include:

• getAllExtras()
• getExtra()
• setExtra()
• clearExtra()
• clearAllExtras()

Filtering by Access

Relations respect all access control rules. When retrieving related streams, the system filters results using:

• testReadLevel()
• testWriteLevel()
• testAdminLevel()
• testPermission()

Automatic Relations: Streams/participating

When a user joins a stream, the platform automatically maintains a relation of type Streams/participating from the user to the stream. This allows fast lookup of participants, live presence updates, and accurate participant counts.

When they leave, the relation is removed automatically.

Maximum Relation Limits

Developers can enforce quotas through checkAvailableRelations(). This is useful for limiting:

• maximum featured items
• NFT minting counts
• index size limits
• rate-limiting categories

Relation Totals

The platform maintains fast-lookup tables:

• Streams_RelatedToTotal
• Streams_RelatedFromTotal

These allow pagination and analytics without expensive COUNT(*) queries, making relations scalable even with millions of edges.

Practical Use Cases

The relations system can represent:

• hierarchical categories
• tagging and many-to-many indexing
• playlists and ordered collections
• threaded discussions
• event-attendee relationships
• user likes and favorites
• recommendation graphs
• game mechanics and scoreboards
• content cross-referencing

Further Reading

For diagrams and deeper conceptual explanations, read:
Qbix Streams as a Graph Database

$results = Streams_Category::getRelatedTo(
  $publisherId,
  $streamName,
  $relationType
);