The Most Legit Use of Namespaces

Namespace is a touchy topic in logseq, as it informs hierarchy and people are trying to judge its worth in a relational database.
And there are two extremes of logseq users, the namespace lovers and naysayers.

  • The first camp extensively applies namespaces for organization, similar to how they would categorize notes or tags in traditional software.
    :point_right: here’s a popular critique from Alex: Different ways to structure data and I agree namespace is easily abused, manually capping the potential of a relational graph.

  • The naysayers have trouble justifying the use of namespace in logseq where it could be done in more flexible ways.
    This quote represents this ethos:

    what’s the benefit of cli-tools/cat over cat (cli-tools) ?

    (This is from @blogbourri in discord in reply to @Bader 's explanation that the namespace concept comes from programming. And Bader’s reply mentions “user preference” and the ability to see “a list of all subpages”, which I don’t think is beneficial enough for people who decided they don’t need namespace in their life.)
    :point_right: To these people, I’ll explain a use case where namespace definitely trumps other methods.

Let me state the conclusion first:

Namespace is mainly useful for one-click retrieval (not only of subpages, but also all backlinks).

Then lemme illustrate:

If you have indented the following blocks like this to show their hierarchy:

- [[project A]]
  - [[subproject 1]]
  - [[subproject 2]]

It totally works for organization (especially if you put it inside an index page or tag the parent block with #index), and it’s flexible — it allows those child pages to be under different parents elsewhere. Make no mistake, I am of the opinion “hierarchy is overrated and mostly a ‘habits die hard’ thing”.

But the benefit of namespace is this:
If one day you want to fetch all info related to project A, you need to write the following query {{query (and [[project A]] [[subproject 1]] [[subproject 2]] ) }} .

  • Note that I only have 2 child links under [[project A]] in my example, but in reality there’re usually more, so the query gets stupidly long.
  • It’s also setting you up for potential mistakes — if you forget a link in the query, you risk missing info.
  • The simple {{query [[project A]] }} could be used to accomplish the same task if every time you tag a block with the subproject, you also tag it with the parent project.
    • but it’s also stupidly tedious
    • and also setting you up for mistakes because who remembers to use all related tags all the time? Not me.

So for purely hierarchical things, not using namespace is actually the more high-maintenance system.

If you use namespace, it’s just one-click. Go to [[project A]] and look down, boom, all backlinks to all its child pages are there in “Linked References”. It also allows me to filter for or filter out a child page there like any other [[link]], which is also a one-click job, much easier than if I’m not using namespace.

So when I use namespaces, it’s almost always for situations like this — for things that are strictly hierarchical (chapters of a book, subprojects that are impossible to be children of multiple projects, …) AND have a meaningful parent that I would want to see backlinks to.

Some people use namespace for very broad concepts and that I would consider abuse:
If the namespace is so broad that you wouldn’t ever want to see all backlinks to everything under it, that’s a useless namespace in my book, and the Wikipedia style of page (category) would be better if you need to disambiguate.

My setup if anyone’s curious:

I filter out all child pages by default, because the Hierarchy section is right below Linked References if I want to see backlinks to child pages, and this way I can use the backlinks to the parent page to check if anything can be tagged with more granularity.
Note that, this way, the “Linked References” is quite similar to if I’m not using namespace but independant tags, but by using namespace I preserve the ability to see the “global backlinks” by removing all filters — I could do that by deleting the hidden page property filters at the top of the page so it’s also one-step.


Also want to make some addition for Wikipedia-like style: it could look like [[[[category]] page]] or [[page [[category]]]]

1 Like

I really wanted to use nested pages when I first started using logseq, but I quickly learned that that is even more prone to bugs than namespace and alias (more corner cases) so I grudgingly parted with the idea (now the itch isn’t as bad as I’ve accustomed to “the way of logseq”.) More than a year has passed and nested pages never got the love or focus. I wouldn’t recommend new users to use it.


Wow I didn’t even know, you can already use nested tags in Logseq.

[[Let's [[test]] nested [[Tag]]s !]]

works for me and creates pages test, Tag and Let's [[test]] nested [[Tag]]s !. test page gets a new entry to Let's [[test]] nested [[Tag]]s ! in Linked references, same with Tag. Given a link Let's [[test]] nested [[Tag]]s !, I can even click on the test or Tag part, which gets me to the corresponding page. If I rename test to test2, the nested page name gets also renamed to Let's [[test2]] nested [[Tag]]s !.

Hence you can create dynamic page names, where partial names can be reused. I am not sure, why this super cool feature is not documented anywhere!

Can you give an example, what buggy things can happen?

1 Like

I feel namespaces definitely have their place for strict hierarchies. The “one-click retrieval” is a good hint. On the other side, this is not quite consistent yet with namespaces in queries.


tags: [[Logseq]]

Now (and [[project A]] [[Logseq]]) doesn’t get me projectA/subproject1. I would expect it to be contained within (or “subkind of”) projectA, similar to the one click retrieval in the hierarchy view.

1 Like
  • one example where basic functionality is broken: Adding # hash tags breaks [[[[Nested]] Page Titles]] · Issue #2954 · logseq/logseq · GitHub
    I heard bugs related to nested pages from time to time, some of them are fixed, but it definitely felt like it takes the backseat and only fixed for compatibility rather than as a core functionality.
  • Its “undocumented” nature is another reason I’m wary. I’ve been part of the logseq community for almost 2 years, and I never saw any team member “advertise” this feature or mention it as some kind of “highlight” / attractive point of logseq. Hence I don’t feel like “this would be working” is a promised thing from the team.
  • By the nature of its construct it already looks like there will be more corner cases and easier to break, especially as I am using logseq’s org-mode where a labelled link or asset link looks like [[destination][description]] rather than the [description](destination) of markdown. If I add nested pages into the mix, it’s a brackets counting game, for both me and the software.

I do really like this feature, so I’m waiting for a sign to use it — if they start advertising it, I’m in.

I also think this is another area that can be helped by the database version they’re planning, because nested pages work well in roam research.

1 Like

I just tested, and get the same number of results by filtering the linked references of [[namespace]] with [[test tag]] and by {{{query (and [[namespace]] [[test tag]] ) }}}.

  • Both retrieve the blocks that include references to both “any page in this namespace” and [[test tag]] (except the page properties block).
  • Both did not retrieve the “page properties” block in the [[namespace/child]] page, which looks like a bug. You could report it on GitHub (mention both filtered linked references and custom queries).

Thanks for those hints! This is one of the cases where I wish there would be more communication from developers. For me this is one of the Logseq “core” features, as it provides an new, additional solution for basic organizing and tagging. I like to think of nested tags as a form of composition, bigger things being constructed from smaller parts. Naming is arguably one of the hardest things in organizing, hence if the program takes care of dynamic names, that would be great!

I see. With Markdown I haven’t encountered any problems so far.

It even works with current approach, no database needed! Markdown files are renamed correctly, when nested!

OK, need to have a second look at it later.

@WQing I guess I’d be one of the naysayers of using namespaces to implement hierarchies, even strict ones (I just outlined some reasons here).

Your post made me realize that this is not only because of flexibility, but because we need both concepts, namespaces, and hierarchies, and we should not mix them up.

I feel that namespaces are a very import and much needed concept, and that they should be reserved for actual namespaces (i.e. disambiguating the same names in different contexts).

Your example is actually an excellent use case for using namespaces (in the Logseq sense) as proper namespaces (in the computer science sense), for keeping things with the same names apart, but not for building hierarchies.

A taxonomy is

The classification and naming of organisms in an ordered system that is intended to indicate natural relationships, especially evolutionary relationships.

A tag like “subproject 1” wouldn’t be part of any properly designed taxonomy. (like “car” in “vehicles”, “cat” in “animals”). On the other hand, there would still be many “subproject 1” around, this is why they need to be put into a namespace, such as “Project 1”/“subproject 1” to distinguish them.

One of the main criticisms of using namespaces to implement hierarchies (in the sense of taxonomies) is that there is no way to centrally edit the hierarchy. If you’ve tagged a page “cat”, once there are a lot of pages, you might want to organize them into a taxonomy without editing each tagged block individually.

One the other hand, in the “subproject 1” case, “subproject 1” isn’t a meaningful name by itself, like “cat” is. It makes sense to centrally sort all of the “cat” blocks under “mammals”, but it doesn’t make sense to centrally reclassify all “subproject 1” tags, because they all live under different projects. A category “mammals/cats” makes sense, a category “All projects/first subprojects” doesn’t.

If someone made the mistake of individually tagging his pages separately with “Project 1”, “Project 2” and “subproject 1”, the tag “subproject 1” by itself is ambiguous. Many projects have a “subproject 1”, and there is no way to further classify them.

That’s why in your case, the use of namespaces is correct, even a naysayer like myself can absolutely agree with this use.

All of these projects should be tagged, as you suggested, “Project 1/subproject 1”.

This is the proper use of namespaces (to keep the same names used in different contexts apart), but not a good example of a hierarchy (in the taxonomic sense, to classify things in a system).

Ultimately, we’ll need a way to specify relations between tags, and these tags could very well be disambiguated by the use of namespaces.

tl;dr namespaces are good for keeping identical names apart, they are not good for taxonomies.


Yes exactly. To say it in other words: child should automatically get tagged with namespace (parent), so that inside child page we can search combinations of tags like (and [[namespace]] [[Logseq]]. This is not consistent yet.

Agreed. It makes sense to define all kinds of relationships between pages/tags via properties. Relationship could be strict hierarchical, polyhierarchical (multiple parents), part-of and so on. Something, which cannot be reflected by using Logseq namespaces. What Logseq currently is missing in my opinion: an effective query and search mechanism for these relations.

One afterthought: I think Logseq namespaces can model a strict hierarchy, if you solely want to model a parent-child relation, with no other kinds of relations. Problem here is: In reality there rarely is one-dimensional thinking. And it definitely would be cleaner design to distinguish between hierarchy and distinguishing namespace as concepts.

1 Like

Have found another bug: Nested tags don’t work, if they start and end with inner brackets, for example: [[[[test]] [[Tag]]]] gets the page name test]] [[Tag.
It works, if you put something either before or after:

  • [[_[[test]] [[Tag]]]]
  • [[[[test]] [[Tag]]_]].

(Not wanting to pollute your post further with non-namespace things, but I don’t even know if this “nested tags” is a feature at all or how it’s called. Some more love for it would be highly appreciated!)

1 Like

I’ve solved this one with advanced queries.
I had a discussion with gax and alex0 in the thread you mentioned, which ended with this post:

It was a lot of fun so to speak :slight_smile:

1 Like

In the Logseq concept, Namespaces don’t make sense. 1 of the advantages of Logseq is that you don’t have to worry, waste time, in which folder to store a file as Logseq does not use folders.

Yet, with Namespaces under which parent, child, grandchild your page or file should be subsumed.

So, while everyone should of course use whichever system works best for them, Namespaces, in a way, don’t make sense here.


As a developer pointed out once, namespaces are meant to disambiguate two different pages that otherwise would have the same name (just like namespaces in some programming languages) :slight_smile:

If you think of them that way there are valid use cases like the ones I mentioned in this thread:

Instead to organize things hierarchically there are better alternatives and indented blocks is one of them. When it comes to pages, the concept of indexes that I described later in that thread is the best one to organize pages hierarchically, in my opinion :slight_smile:


thanks for the explanation.

I looked at the page you linked to, and boy there is some impressive stuff in there. I have no database background and am a Logseq newbie so a lot of the stuff discussed there is a bit beyond me.

We may see some interesting developments in Logseq yet.

1 Like

To add a practical example to Alex’s answer:

Namespaces are useful for keeping the same name apart if used in different contexts. Think about “apple”, which could be a fruit, a company etc.

So you can use a namespace “companies/apple”, “fruits/apple” to keep them separate.

A programming example would be if you have multiple functions named “print”, you could keep them apart by namespaces “std::print”, or “myLibrary::print”.

That doesn’t imply a taxonomy (a system for organizing things into different categories), it is just to keep the names apart. More details in my other answer above.

Unfortunately the two concepts get mixed up in Logseq, which causes a lot of confusion.

Thank you. I still have a lot to learn. I guess I won’t be confronted with the issue because I always try to use unique page names. To take the apple example, I would call 1 of the 2 pages Apple-company and the other Apple-fruit, so a search for apple would yield 2 results.

As for taxonomy, I am reading a non-fiction book and making notes with the built-in PDF viewer. I made a 1st page with some early notes that set the scene.

After that I make a page for each chapter or group of chapters that deals with a specific issue. In the page properties I have a property called parent, and I put a link to the parent there. In the parent properties I have a property called children where I have put a link to each of the children, all of which have their own unique name.

Being a newbie, I am not sure if this is a reply that is relevant to your comment. If it is not, I apologize.

1 Like

I’m still on the fence for one of my namespaces. I have notes for DnD (Dungeons & Dragons)
I had a very involved namespace for it, but made it a little bit more manageable by changing DnD/campaign name to DnD campaign name.
However for one campaign I ran I moved my Google docs to Logseq 1 to 1. There’s a lot of files and my hierarchy now looks like this:

And that’s just a fraction of the total amount.

This seems a legit use of namespaces as most of those pages won’t make sense in terms of their name on their own.

Anyone any thoughts on this? (Really enjoying these discussions on structure tbh!)

There are a couple of good reasons to use real namespaces instead of unique names

  • A namespace tells you what the namespace, and what the name is. Is Apple-fruit in namespace “fruit”, or is “Apple-fruit” some common name? What about “Mary-Jane”?
  • you can use search functionality to query namespaces (see also other answers from @Siferiax ), Logseq doesn’t know that “Apple-fruit” is a fruit.
  • one might be required to use certain names for compatibility with other users (e.g. courts use naming conventions like “Exhibit A”)
  • two people might have picked the same name, and you want to merge the graphs
  • print is a name of the function, and it wouldn’t be a good idea to rename it everywhere to print_std)
  • if you have a given taxonomy, you wouldn’t want to rename the individual groups to avoid conflicts with your own preexisting tags. E.g. you decide to classify animals. A housecat would be under
    Animalia > Chordata > Mammalia > Carnivora > Feliformia > Felidae> Felinae > Felis > F. catus. (I am using “>” to show that we are not talking about the namespace operator “/” in Logseq.
    But what if you already have a page “Felidae” (for the movie)?. You could rename “Felidae” into “Felidae-animal-kingdom”, but now you are not using the established naming scheme for animals, but your own. This will cause confusion. So instead, you create a page for each group in its own namespace AnimalTaxonomy/AnimaliaAnimalTaxonomy/F. catus. Then each page gets a property that tells which parents (one or more) it has.
  • If you use namespaces, you get some syntax checking when you enter the names. Otherwise it’s really easy to accidentally end up with lot’s of synonyms, like Apple-company, Apple-business, Apple-corporation, Apple-corp etc.
  • You can rename namespaces in bulk (still needs a script, but hopefully will eventually be part of a tag management UI)

That’s a good way to do it.

If you want to dig deep, look at these posts: Specify and display relations between pages/tags , Would a rich commitment to hierarchies and classification be an anathema to Logseq culture? , Knowledge Management for Tags / Tag Hierarchies