Clarifying the ConjunctiveGraph deprecation: recommend Dataset(default_union=True)?

[scott-huberty]

I have a small suggestion regarding the deprecation of ConjunctiveGraph in rdflib 7.x and how users are expected to migrate their code.

EDIT: This is related to the discussion happening over at #2591

Minimally Working Example

Say I have some pre-existing script that used ConjunctiveGraph:

from rdflib import ConjunctiveGraph

DATA = (
    "<http://example.org/subject> "
    "<http://example.org/predicate> "
    "<http://example.org/object> "
    "<http://example.org/graph> .\n"
)

g = ConjunctiveGraph()

g.parse(data=DATA, format="nquads")
g.serialize(format="ttl")

'@prefix ns1: <http://example.org/> .

ns1:subject ns1:predicate ns1:object .\n\n'

This makes sense: the triple was in a named graph, but ConjunctiveGraph exposes the union of all graphs, so serializing to Turtle produces a non-empty triple-only view.

Migration per the deprecation message

DeprecationWarning: ConjunctiveGraph is deprecated, use Dataset instead

If I follow that guidance literally:

from rdflib import Dataset

DATA = (
    "<http://example.org/subject> "
    "<http://example.org/predicate> "
    "<http://example.org/object> "
    "<http://example.org/graph> .\n"
)

g = Dataset()
g.parse(data=DATA, format="nquads")
g.serialize(format="ttl")

'\n'

The default graph is now empty. I guess this also makes sense, as Turtle is a triple-only format, so serializing this Dataset’s default graph (which is empty) produces no triples.

But it is not equivalent to the behavior of ConjunctiveGraph, which returned the union.

Suggestion

Since ConjunctiveGraph was historically used specifically as a union-of-all-named-graphs view, and Dataset(default_union=True) is the only construct that preserves those semantics, should the deprecation message explicitly recommend Dataset(default_union=True) instead of the bare Dataset()?

I think you hint at exactly this in your source code:

rdflib/rdflib/plugins/parsers/hext.py

Lines 109 to 110 in 72a98ed

	# Set default_union to True to mimic ConjunctiveGraph behavior
	ds = Dataset(store=graph.store, default_union=True)

---

As an aside, there's no API docstring for the default_union parameter of Dataset, which made it harder to discover and reason about.

[edmondchuc]

That sounds sensible - and the RDFLib docs could certainly benefit from more improvements.

Would you be open to contributing this suggestion as a PR?

I'd also be very interested to hear your perspective on changing default_union to True for Datasets in v8. #2591 (reply in thread)