GetDocumentByKey Frustrations

I got a phone call from a client a few weeks ago reporting a bug. From his non-technical description I knew what the problem was straightaway. Luckily I was due on-site the next day, so I could fix it then and save some face in the process.

The problem was the view.GetDocumentByKey(key) method. Well, the problem was my coding actually, but hear me out while I pass the blame on to Lotus (as I did with the client, who agrees with what I am about to say). As we all know there is an optional argument to this method called ExactMatch. My code didn't set this to True and so the code didn't run as I had expected. Even with my, ahem, extensive testing I failed to account for what can happen when Notes decides it's found a "match".

What I can't fathom is why on earth the ExactMatch option defaults to False? Who has ever used it with False? Why?

This time I swore I would learn and always be sure to set the argument to True. I'm now going to run up and down the street naked, screaming "I must set ExactMatch to True", while giving myself a good twigging.


    • avatar
    • Andy Barber
    • Wed 23 Mar 2005 09:12

    Man have I fallen into that trap before !!!

    Although I do use exactmatch set to false quite a lot when I want to do fuzzy lookups....it does have its uses but I agree the default should be set to yes.

    Crackin' site by the way

    • avatar
    • GetDocumentByKey(true)
    • Wed 23 Mar 2005 09:21


    Och aye

  1. I too have fallen victem to that and have flogged myself for it until moral did indeed improve. Defaults for anything similar to this should always always always be set to restrict the data returned instead of allowing leeway. Opens us all up to sloppy programming, as if there isn't enough of that going on.

    On another note, did we really need that imagery? I'm sure the neighbors would find it humorous, as would your significant other (until she has to post bail), but still, *gag* Not a picture to get in one's head at 10 in the morning... or any other time.

    • avatar
    • Mike
    • Wed 23 Mar 2005 09:52

    Lotus Notes - when you burn, you learn. I've actually woken up in the middle of the night and wondered if I had set the flag to True for a client I was no longer working for.

    -- Mike

  2. Yes, this one has burned me before as well. I have often wondered why it is set to false by default, seems backward to me.

    PS: New site design is awesome!

    • avatar
    • Romano soprano
    • Wed 23 Mar 2005 10:39

    Well, it gets even worse. When using categorized embedded view and the 'show single category' option, the view can show category that only partially matches the key. I learned it this monday morning - got a phone call from an upset client before I managed to drink my first cup of coffee. Frustrating. And you _don't_ have the option of forcing exact match. Some discussion here {Link} and here {Link}

    You were warned.

  3. Mate, in R5, 'GetDocumentByKey' and 'GetAllDocumentsByKey' sometimes fail to produce a match even if you're positive that there is one or more documents containing your key.

    Only happens once in a blue moon, but particularly annoying (and embarrassing) if you're trying to do some relational-type activity such as updating documents with fields that match your key.

    Ironically, I've often resorted to using 'GetDocumentByKey(SearchKey, False)' deliberately so I can test the resulting collection myself and narrow it down to the docs that Lotus missed!

  4. Not only is the single-category problem discussed on Notes.Net / LDD / developerWorks, a solution has been posted many, many, many times:

    "Albania" starts with "Alban"

    "Albania~" does not start with "Alban~"

    By the way, you can use a more "display-friendly" character (including some that render as spaces) if you find the tilde offensive.

    I believe that False is the default in order to avoid problems with case and accent. If that's the case, then I can see it as the default -- but the documentation should be much clearer about the default behaviour. Big bold, red flashing letters. The same applies to a lot of Designer Help. That said, it's still a lot clearer than a lot of the doco I've waded through in my time....

  5. While you're chanting naked, don't forget:

    "I must set 'Option Declare'"

    "I must set 'Option Declare'"

    "I must set 'Option Declare'"

    "I must set 'Option Declare'"

    "I must set 'Option Declare'"

    "I must set 'Option Declare'"


    • avatar
    • andy
    • Wed 23 Mar 2005 17:17

    Has anyone tried embedding a single category calendar view on a page that displays and getting to display 1 month at a time to show.

    Firstly, this results in a catch 22 problem, as the first column, you want to restrict to a category, but you also want it to contain a date to display in the calendar.

    Secondly the option to view as a 1 month view doesn't show as an option, unless you leave the view open in the client then edit and save the view in designer, when returning to the view in the client it has the 1 month option, but only until you exit the view.

    Then it dissapears, has anyone else come across this ?


    • avatar
    • Carl
    • Wed 23 Mar 2005 21:53

    I use the false option quite a lot when I have dynamic lookups, for patrial phone numbers, or I know the persons name begins with kingm was it kingsy or kingsly? that option lets me easily retrieve the docs that match and allow people to select the one they want.

    perhaps the default is the wrong way around, but I can't remember if the first time getdocumentbykey came around it had the exact match option? So might be for compatibility reasons.

    • avatar
    • wekar
    • Thu 24 Mar 2005 01:20

    I imagine this trap sucks to fall into, but I've never forgotten to include (key, true) since R5 came out... because, back the exactMatch argument didn't exist, and after the first time I fell into that trap I always had to write my own code to doublecheck the returned document. (key,true) is just automatic now, unfortunately so are other things like view.refresh even when not needed (post R4).

    • avatar
    • wekar
    • Thu 24 Mar 2005 01:21

    back in R4 exactmatch wasn't even an optional argument that is.

  6. Could you tell us the street's names ?

    • avatar
    • Alec
    • Thu 24 Mar 2005 07:11

    I can understand use 'false' in applications such as a phone directory.

    What I don't understand is when my documents are keyed with unique keys of identical length, how not specifying 'true' sometimes fails to retrieve the desired document when I can demonstrate the document with 'key' does exist.

    Yeah, this one has bitten me and now it is my shop's policy to always specify 'true' unless a specific need determines otherwise.

    As an afterthought, we have started to use GetDocumentByUNID instead of GetDocumentByKey as we have determined this is definitively faster. The downside is the need to be careful when copying/moving documents between databases (for testing, demo-ing, and such) that we update dependent keys in relationships.

    • avatar
    • Michael
    • Thu 24 Mar 2005 09:09


    You arguments make sense but I have no sympathy for you on the expectation end as it's clearly spelled out in the help file. It's similar to fixing a @DbLookup that won't return new records entered because the "NoCache" option wasn't specified.

    As for the blame game, I'm wondering if someone without your stellar credentials/reputation would have received the same agreement from the client. Forget the twigging and just pair your socks randomly for a few days. That will drive home the exact match message. :)

    Oddly, the @DbLookup also has [PARTIALMATCH] as an optional keyword, so it's curious why they made it the default for GetDocumentByKey.

  7. You could use it with the switch for building a collection of collections in Java where you supply a collection of generic keys (A,B,C) to then grab a series of ViewEntryCollections for each key. This would be done to mitigate memory issues with huge ass views, allowing you to process them in logical chunks.

    Beyond that, I've just made it a habit to set true, as I'm sure everyone else has. One other thing, I'm sure it's set to False as that's default behaviour for any boolean.

    • avatar
    • Matt
    • Mon 28 Mar 2005 15:34

    Lotus seems to like adding complexity without a prior need. I think this is just another example.

  8. The [PartialMatch] for @DbLookup was actually introduced in R6. So, the defaults have been different before, just without a way to use the other option.

Your Comments


About This Page

Written by Jake Howlett on Wed 23 Mar 2005

Share This Page

# ( ) '


The most recent comments added:

Skip to the comments or add your own.

You can subscribe to an individual RSS feed of comments on this entry.

Let's Get Social

About This Website

CodeStore is all about web development. Concentrating on Lotus Domino, ASP.NET, Flex, SharePoint and all things internet.

Your host is Jake Howlett who runs his own web development company called Rockall Design and is always on the lookout for new and interesting work to do.

You can find me on Twitter and on Linked In.

Read more about this site »

More Content