RFC 2259
Simple Nomenclator Query Protocol (SNQP)
RFC 2259: Simple Nomenclator Query Protocol (SNQP) 💖
okay bestie, so this is RFC 2259 ✨ it's called Simple Nomenclator Query Protocol (SNQP), it came out of the Network Working Group in January 1998, and it's Informational 🎀 The authors are J. Elliott from Epic Systems Corporation and J. Ordille from Bell Labs, Lucent Technologies 🦋 It doesn't list anything it obsoletes or updates, so it's just vibing on its own 🌸
Status of This Memo ✨
this memo is giving "for information only" 💅 It's here to inform the Internet community, and it does not set any Internet standard of any kind. Distribution of this memo is unlimited 🌈
Copyright Notice 🫶
Copyright (C) The Internet Society (1998). All Rights Reserved. 💜
Abstract 🌸
okay so the Simple Nomenclator Query Protocol (SNQP) lets a client chat with a descriptive name service or some other relational-style query service 💖 It's super useful for services that dig through a bunch of data repositories to find query responses 🔍 Clients can pose queries on relations, list descriptions of relations, and get advice on how to reduce the search time and cost of their queries 💅 Clients also get told how old the information in caches is, and they can ask for more recent info if they want it ✨
SNQP has support for graphical user interfaces 🎀 It also supports different types of comparison operators, so services can use SNQP with a whole mix of back-end servers, like relational database servers, CCSO servers, and servers providing relational views of X.500 🦋
SNQP is an ASCII protocol with the same request-reply vibe as SMTP 💕 It was specifically designed for the Nomenclator name and information service, and it's been useful elsewhere too 🌟
1. Introduction 🦋
okay so the Simple Nomenclator Query Protocol (SNQP) is a protocol for querying servers that search collections of data repositories 💖 Users get information from an SNQP server by describing attributes of the info they want ✨ SNQP servers can contact one or many data repositories to get the response to a user's query 🔍 If the data repositories differ in protocol or data format, it is the responsibility of the SNQP server to translate protocols and data formats so the user gets one integrated answer 🎀
SNQP servers share the protocol needs of centralized data repositories that answer queries with locally stored data 💅 They also need some specialized protocol features because of their distributed search characteristics 🌸
in highly distributed environments, it is unreasonable to expect every data repository that needs searching to be available whenever queries are posed 😭 So SNQP servers need facilities for returning partial results when there are communications errors with data repositories 🫶 The partial results must indicate how to resubmit the query only to those data repositories that are unavailable 💜
also, users may pose queries without realizing how costly the search for query responses can be 💀 SNQP provides facilities for telling users about query costs and advising them on limiting that cost ✨ Costs and advice are returned before queries are executed 🌈
last but not least, SNQP servers may cache data and meta-data to speed up query responses ⭐ Servers can tell users the t-bound for their query response 🎀 A t-bound is the time after which changes may have occurred to the data that are not reflected in the query response [6,2]. A t-bound is the time of the oldest cache entry used to calculate the response 🦋 Users can request that query responses be more current than a particular t-bound 🌸 Making such a request flushes older items from the cache 🧚
SNQP has support for graphical user interfaces 💖 It also supports different types of comparison operators, so SNQP servers can query a variety of back-end data repositories, like relational databases, CCSO servers [3], and servers providing relational views of X.500 [10] 💅
SNQP is a connection-oriented protocol 🎀 A client starts a query session with an SNQP server by making a TCP connection to a well-known port ✨ Then the client runs a series of SNQP commands 💕 These commands are listed briefly in Table 1 🌸 Section 2 gives some typical scenarios for using these commands, and Section 3 describes the commands fully 🦋 The server replies to each command using the theory of reply codes described for the Simple Mail Transfer Protocol (SMTP) [9] 💜 The theory of reply codes and the defined reply codes are described in Section 4 🫶
---------------------------------------------------------------------
Command Description
---------------------------------------------------------------------
advice Provide advice on query costs without executing
query.
attributes List the attributes for a relation.
compare Set type of comparison operation.
help Explain the SNQP commands.
imagui Format replies for a graphical user interface.
next Stop processing current query, continue with next
query in block.
noadvice Provide responses to queries. Do not advise
on costs.
noimagui Format replies for people.
query Submit a block of one or more SQL query statements.
relations List the relations available through the SNQP
server.
stop End processing of current query, and cancel any
queries remaining in block.
quit Terminate the query session.
Table 1: SNQP Commands
---------------------------------------------------------------------SNQP queries are posed in SQL, a standard relational database query language [4,12] 🌈 Info obtained through SNQP servers is organized by type into database relations 🍓 SQL queries may often have more functionality than a server supports or an application demands 😭 Also, advice on query costs, some types of comparison operations, or t-bounds may not be supported by a particular server 💀 SNQP defines a minimal subset of functionality for a working SNQP protocol 💖 Functionality beyond this subset is optional 🎀 Servers that do not support optional functionality must return replies that indicate this to the user ✨ The required and optional features of SNQP are summarized in Section 5 🦋
SNQP was specifically designed for use with the Nomenclator name and information service [8,7,5] 💅 Nomenclator produces query responses by integrating information from data repositories with different protocols and data formats 🌸 It constrains the searches for query responses through a variety of distributed indexing techniques 🧚 SNQP has also been found useful elsewhere, even as a query language for a single data repository 🫶
SNQP is defined for US-ASCII only, and use with other character sets will require further work 🌟
Section 6 concludes this document with a description of security considerations 🔥 (and yes, bestie, take those seriously 😭)
2. Scenarios 🎀
this section shows the basic SNQP commands through a few client scenarios 💖 We've got a new user, a user who prefers CCSO style comparisons and more current responses, a graphical user interface program, a user with a change of mind, and a user worried about costs 💅 SNQP will work for a human client on a bare connection (like one provided by telnet), but it also works for client programs too ✨ Several of these programs have been written and they provide enhanced interfaces 🦋
2.1 New User 🌸
a new SNQP user will first make a tcp connection to an SNQP server 💕 For purposes of illustration, we'll assume the user makes the connection with the Unix telnet command, and that the server is located at nomen.research.bell-labs.com on port 4224 🧚 The user enters a relation command to discover what relations are available, and an attributes command to discover the attributes for a particular relation 🫶 Eventually the user asks for people with a given name of "J*" and a surname of "Ordille" who work for "Lucent Tech*" 💜 The response is current through June 11, 1996 at 11 p.m. EDT 😭 Figure 1a and Figure 1b show this scenario 🌈
> telnet nomen.research.bell-labs.com 4224
Trying 135.104.70.9...
Connected to nomen.research.bell-labs.com.
Escape character is '^]'.
220 nomen.research.bell-labs.com Nomenclator Query Service ready
relations
211-There is 1 relation defined:
211 People
attributes People
212-There are 20 attributes in relation "People":
212-Given_Name
212-Middle_Name
212-Surname
212-Name_Suffix
212-Title
212-Organization
212-Division
212-Department
212-Building
212-Street
212-City
212-State_or_Province
212-Postal_Code
212-Country
212-Phone
212-Fax
212-Email
212-MHSmail
212-Last_Modified
212 Source
Figure 1a: New User Queries Server query
350 Send the query text, end with .
select * from People where
given_name = "J*" and surname = "Ordille" and
organization = "Lucent Tech*";
.
351 Partial response follows, ended with .
Given_Name: Joann
Middle_Name: J.
Surname: Ordille
Title: MTS
Organization: Lucent Technologies
Division: Bell Laboratories
Department: Computing Sciences Research Center
Building: 2C-301
Street: 700 Mountain Avenue
City: Murray Hill
State_or_Province: New Jersey
Postal_Code: 07974
Country: United States
Phone: +1 908 582 7114
Email: joann@bell-labs.com
Source: nomen://bell-labs.com:17036/email=joann@bell-labs.com
.
250 All queries processed. Current through 11-Jun-1996 23:00 EDT.
quit
221 nomen.research.bell-labs.com closing transmission channel
Connection closed by foreign host.
Figure 1b: New User Queries Server
(continued)2.2. User with CCSO and Currentness Preferences 💅
okay bestie, this user grew up on CCSO name servers 🧚 and she is obsessed with CCSO word-based matching inside attribute strings. Every word in her query string for an attribute has to show up somewhere in the response string, in any order, no cap. The wildcard * matches any substring within a word. The default matching (see Figure 1b) is exact matching of a query string, but the query string can include * wildcards that match any substring within the response string. Both types of matching are case insensitive, so caps don't matter 🙈
In Figure 2 it gets iconic ✨ The CCSO-style user connects to the SNQP server, enables CCSO matching, and asks about Ordille, who works in research at a lab division of some company. She wants info that is more current than June 11, 1996 at 11 p.m., if it's available 🌸
compare ccso
213 Performing ccso equality comparisons
query 11-Jun-1996 23:00
350 Send the query text, end with .
select given_name, surname, organization, division, department,
email from People
where surname = "Ordille" and department = "research"
and division = "lab*";
.
351 Partial response follows, ended with .
Given_Name: Joann
Surname: Ordille
Organization: Lucent Technologies
Division: Bell Laboratories
Department: Computing Sciences Research Center
Email: joann@bell-labs.com
.
250 All queries processed. Current through 12-Jun-1996 22:35 EDT.Figure 2: User with CCSO Preferences Queries Server
2.3. Graphical User Interface Program 🦋
a user built a Windows program as a front end to the SNQP server 🪟 In Figure 3, the program asks for replies formatted for a graphical user interface program. It submits two SQL queries and gets back detailed responses that show the type and position of each error. We'll dig into those error messages in Section 3 🔍
imagui
214 GUI responses enabled
query
350 Send the query text, end with .
select * from Peple where name = "Elliott";
.
735 00000001a000015 e Unknown relation, "Peple"
735 00000001a000027 e Attribute "name" not found in any relation used.
250 All queries processed. Current through 12-Jun-1996 22:35 EDT.
query
350 Send the query text, end with .
select * from People wher surname = "Elliott";
.
730 00000001a000022 e syntax error
730 00000001a000027 e syntax error
730 00000001a000037 e syntax error
730 00000001a000039 e syntax error
250 All queries processedFigure 3: Graphical User Interface Program Queries Server
2.4. User Changes Mind 🙃
an exuberant user decides to search everywhere for family members 👨👩👧 Then she wants to look up a friend who works at Epic Systems, and finally she wants to search everywhere for an old school friend 🏫 Once the query set starts, she realizes the folly of searching everywhere, so she stops the first query, runs the second one, and then stops executing the query block. It's all shown in Figure 4. The t-bound is represented by <time> in this scenario because of space restrictions 📏
query
350 Send the query text, end with .
select * from people where surname = "Smith";
select given_name, surname, email from people
where surname = "Elliott"
and organization = "Epic Systems*";
select * from people where surname = "Brown";
.
next
352 Starting next query. Any pending responses discarded.
351 Partial response follows, ended with .
Given_Name: Jim
Surname: Elliott
Email: jim@apocalypse.com
.
352 Beginning next query. Previous current through <time>.
stop
251 All pending queries and responses discardedFigure 4: User Changes Mind About Submitted Queries
2.5. User Worries About Costs 💸
in Figure 5a, the exuberant user gets a little more careful 🧐 and asks for advice on searching for a friend named "Susan Brown". She can't recall the name of the organization where Susan works, but she remembers the state name starts with "I". The advice response lists the locations of the data repositories that will be contacted. These locations can be given to the SNQP server using the "source" attribute 🗂️ Each location is followed by a blank and a descriptive phrase for the data repository. Continuing in Figure 5b, the SNQP server also supplies a list of attributes that may constrain the query further. She recognizes the name Northeastern and sends the query straight to that location 🎯 She could also have added organization = "Northeastern*" to the original query. Other advice options are covered in Section 3 💖
advice
214 Basic advice enabled. Query responses disabled.
query
350 Send the query text, end with .
select * from people where surname = "Brown" and
given_name = "Susan" and
state_or_province = "I*";
.
354 The query will contact 8 data repositories, ended with .
ccso://ns.dacc.cc.il.us:105/* Danville Area Community College
ccso://ns.eiu.bgu.edu:105/* Eastern Illinois University
ccso://ns.ilstu.edu:105/* Illinois State University
ccso://ns.imsa.edu:105/* Illinois Math and Science Academy
ccso://ns.ne.edu:105/* Northeastern Illinois University
ccso://ns.uiuc.edu:105/* University of Illinois at Urbana-Champaign
ccso://ns.iup.edu:105/* Indiana University of Pennsylvania
ccso://ph.indstate.edu:105/* Indiana State University
.Figure 5a: User Asks About Costs Before Executing Query
355 There are 8 attributes that may constrain the query, ended with .
Organization
Department
Email
State_or_Province
Country
Postal_Code
Phone
Source
.
250 All queries processed. Current through 12-Jun-1996 22:35 EDT.
noadvice
214 Query responses returned. Advice disabled.
query
350 Send the query text, end with .
select * from people where surname = "Brown" and
given_name = "Susan" and
state_or_province = "I*" and
source ="ccso://ns.neiu.bgu.edu:105/*";
.
351 Partial response follows, ended with .
Given_Name: Susan
Middle_Name: W.
Surname: Brown
Organization: Northeastern Illinois University
Email: sw-brown@ne.edu
Source: ccso://ne.edu:105/alias=SW-Brown
.
250 All queries processed. Current through 12-Jun-1996 22:35 EDT.Figure 5b: User Asks About Costs Before Executing Query
3. Commands 🎀
SNQP commands are case insensitive and end with a newline <LF> or a carriage return <CR> 📝 In the descriptions below, SNQP commands are in upper case and SNQP replies are in mixed case. Items in a command list are separated by blanks.
Most SNQP replies are short 💫 They have a reply code (see Section 4), followed by a continuation character and the reply text. If the continuation character is blank, the reply is complete. If the continuation character is a dash ("-"), the reply keeps going on the next line. The text in a reply can vary, but the reply code stays the same. Here's a two-line reply example:
nnn-Message1
nnn Message2Sometimes commands or replies get long, so they use the '.'-terminated block structure that SMTP uses for message bodies 📦 Blocks are made of lines of text that make up the command or reply. A block ends with a period on a line by itself.
SNQP generally ignores blank lines in both directions, except that blank lines separate tuples within query response blocks 🫧
Whenever a time is listed in a command or response, it uses this format:
DD-MMM-YYYY HH:MM ZZZHere DD is the day, MMM is the first three characters of the month, YYYY is the year, HH is the hour on a 24-hour clock, MM is the minutes, and ZZZ is a commonly used US timezone abbreviation. If the time zone is left out of a command, the timezone of the SNQP server is assumed 🕰️
SNQP servers support a source attribute in every relation 🗺️ In queries, the source attribute points the SNQP server to a particular data repository. In query responses, it shows where the information in a tuple came from. In advice and error messages, the source attribute is provided so the client can contact the source in later queries. The source attribute has two possible forms:
<protocol>://<domain-name>:<port>
<protocol>://<domain-name>:<port>/<tuple-id><protocol> identifies the protocol used to contact the data repository. The data repository can be (was) contacted at <domain-name> and <port>. When it's present, <tuple-id> identifies a specific entry in the data repository. It's missing when the data repository doesn't have an attribute that uniquely identifies its entries 🔑 The source string looks a lot like a URL, but the protocols listed may or may not be supported by World-Wide Web browsers. An effort should be made to keep the protocol identifiers consistent with accepted standards, but in the end they are specific to SNQP servers 🌈
When a connection is set up with an SNQP server, the server sends back this greeting, where <domain-name> is the domain name of the server host (e.g. nomen.research.bell-labs.com) and <service-name> is the name of the service (e.g. Nomenclator) 👋
220 <domain-name> <snqp-service-name> Query Service readyThe following sections describe each command in detail 📚 The commands are in alphabetical order. Typical reply messages are explained with each command. Exceptional error conditions, like system errors or rejecting connections due to load, may sometimes happen. These error replies are documented in Section 4 🙈
3.1 Advice ✨
---------------------------------------------------------------------
ADVICE
214 Basic advice enabled. Query responses disabled.
514 Advice not available
ADVICE <RELATION> <ATTRIBUTE>
214 Advice enabled for "<attribute>" in "<relation>"
553 Unknown relation
554 Unknown attribute
514 Advice not available for "<attribute>"
---------------------------------------------------------------------okay so advice is a whole vibe 💅 in every case, advice turns off query searches. Once you send queries, advice tells you what they'll cost or how to narrow them down. There are two forms of the command, and they're both giving different energy 🎀
The first form has no attribute name. When an SQL query gets processed, the SNQP server sends back a list of the data repositories it's gonna contact 🧚 It also gives you a list of attributes that might constrain the query more. The actual values of those attributes decide whether the query gets constrained further. If the server can't give advice, you get an error.
The second form includes a relation name and an attribute name from that relation 🦋 SQL queries send back a list of possible values for that attribute. The list might be complete, or it might only have values that are known to constrain the search. There's more about that difference in the query command. If advice isn't available for the attribute, or the relation or attribute is unknown, you get an error. Also, if advice isn't available on one attribute, basic advice and advice on other attributes might still be available, so don't give up yet bestie 🫶
Basic advice and attribute advice can be enabled at the same time. They are not mutually exclusive, so you can have both going 🌈
The advice command is honestly so useful for application programs that show lists of options to the user 😭 A query-form program can enable advice for an attribute, submit an empty query, and grab the list of options for that attribute. The list tells you whether it's a full list of every value, or a constraint list of only the values that actually constrain queries. A program can turn full lists into a selection menu on its query form 🍓 Or it can enable basic advice, submit the query, and then ask the user to pick which data repositories to search from the results. Iconic 👑
3.2 Attributes 🌸
---------------------------------------------------------------------
ATTRIBUTES <RELATION> <TIME>
212-There are <n> attributes in relation "<RELATION>":
212-<Attribute-name>
212-<Attribute-name>
212 Current through <TIME>
553 Unknown relation. Current through <TIME>.
556 T-bounds not supported
---------------------------------------------------------------------The attributes command lists the attributes defined for a given relation 📋 Here's the tea: characteristics of relations can be defined outside the SNQP server and cached there, so the user can ask for an answer that's more recent than <TIME> ✨ The SNQP server will endeavor to provide that info. The first line of the reply tells you the number of attributes, <n>. The lines after that list the attribute names. Everything in the response is current through the time it returns, but it could change after that point 🕰️ Accepting requests to improve a t-bound, and indicating the t-bound of the result, are optional for SNQP servers 💜
If the relation is unknown, you get an error. If <TIME> gets submitted when t-bounds aren't supported, you also get an error. Not me getting errors for being unsupported 💀
3.3 Compare 🦋
---------------------------------------------------------------------
COMPARE <COMPARISON-TYPE>
213 Performing <COMPARISON-TYPE> comparisons
555 Unknown comparison type
---------------------------------------------------------------------The compare command lists the type of equality comparison used for SQL queries 🔍 You can follow the command with a comparison type to set it. Reply 555 comes back if the comparison type is unknown or unsupported 🙈 "Default" and "CCSO" are the defined comparison types. The default equality comparison is exact string matching. In that one, the query string can include * wildcards, which match any substring within the response string 🎀
CCSO equality is giving word-based matching. Every word in the query string for an attribute has to appear, in any order, in the response string 🧚 Words are separated by a blank, comma, colon, semi-colon, tab, or newline. Inside CCSO, the * wildcard matches any substring within a word. And honestly, both string and word comparisons are case insensitive, so capitals don't matter 💖
3.4 Help 🌈
---------------------------------------------------------------------
HELP
210-The following commands are available:
210-<comma-separated-command-list>
210 <comma-separated-command-list>
HELP <COMMAND>
210-<explanation of <COMMAND>>
210 <explanation of <COMMAND>>
500 Sorry, no help available for "<COMMAND>"
---------------------------------------------------------------------The help command returns the list of available commands 📜 If some commands aren't supported (advice, for example), they should not be listed. But using an unsupported command should still give you an informative error message, so you're never left hanging 🫶 You can follow help with a command name to get info on that command. If there's no help for a command, or the command doesn't exist, you get Reply 500 💅
3.5 Imagui 💖
---------------------------------------------------------------------
IMAGUI
215 GUI responses enabled
---------------------------------------------------------------------The imagui command tells the server that the client is a graphical user interface (GUI) 🖥️✨ The client is asking for more comprehensive, program-oriented errors and progress reports, and the server replies that GUI responses are enabled. Check Section 4 for more on GUI responses 🦋
3.6 Next 🍓
---------------------------------------------------------------------
NEXT
353 Starting next query. Any pending responses discarded.
450 No query in progress
---------------------------------------------------------------------The next command stops processing the current SQL query, then starts the next SQL query in the block submitted with the last query command 🏃♀️ If none are left, the query command is completed. If no query is in progress, you get an error 😭
3.7 Noadvice 🧚
---------------------------------------------------------------------
NOADVICE
216 Query responses enabled. Advice disabled.
---------------------------------------------------------------------The noadvice command disables advice for query commands 🙅♀️ It also activates query searches, so queries will return responses again. See the advice command for more info 💜
3.8 Noimagui 🌸
---------------------------------------------------------------------
NOIMAGUI
215 GUI responses disabled
---------------------------------------------------------------------The noimagui command disables detailed messages to a graphical user interface program 🫠 It replies that GUI responses are disabled. Section 4 has more info on GUI responses, so go check it out 🎀
3.9 Query 💅✨
okay so the query command acts totally different depending on whether responses or advice are turned on 🫶 we'll go through how you submit a query and the immediate errors you can get back first, then the replies you see when responses are on, and then the replies you see when advice is on 🔥
QUERY <TIME>
350 Send query text, end with .
450 Query already in progress
552 Query blocks are limited to one SQL query
556 T-bounds not supportedbestie, the query command sends a whole block of SQL queries to the SNQP server 🎀 each SQL query has to end with a semi-colon, and the entire block ends with a line that has just one period on it 🦋 if you want special characters inside string constants, you use C language conventions, so "\n" means newline 🌸
the user can ask for answers that are more recent than <TIME> 👑 the SNQP server will try its best to give that info, since a bunch of cached stuff can get used while processing the queries 💜 supporting requests to improve a t-bound is optional for SNQP servers, so they don't all have to do it 🙈
now the errors 😭 if a query command is already running, the whole block gets refused, no exceptions 💀 if you send several SQL queries in one block to a server that can't do multi-query blocks, you get an error 💅 and if you send a <TIME> when t-bounds aren't supported, you also get an error 🥀
351 Partial response follows ended with .
352 Beginning next query. Previous query current through <TIME>.
250 All queries processed. Current through <TIME>.
653 <Communications err> with <location> <location description>
660 <Error> from <location> <location description>
700 <SQL query parsing error>
750 <SQL query semantic error>
761 <Requirements Error> for <location> <location description>the responses come back in blocks as soon as they show up from the data repositories ✨ reply 351 kicks off a response block, and response blocks end with periods 🍓 inside a block, tuples get sent as a list of attribute name and value pairs, like this:
<attribute-name>: <attribute-value>
: <attribute-value>only the first line of a multi-line attribute has the <attribute-name> on it, and successive tuples are separated by blank lines 🧚 attributes with null or blank values can be left out, but that's up to the SNQP server 🌈
between response blocks you can also get error replies, and 653, 660 and 761 are the main examples 😭 reply 653 is a communication error with the data repository, identified by its source location and described by the attached string 💜 reply 660 is an error that the data repository itself returned 🔥 and reply 761 means the query didn't meet a known requirement of the data repository 🙈 the SNQP server works this out by comparing your query against what it knows about the data repository's characteristics, so for example some data repositories refuse queries that don't include a certain subset of attributes in the relation 💅 other replies are possible too, so just check the type and severity of the reply against the theory of reply codes in Section 4 ✨
after an SQL query in the block finishes successfully, the SNQP server sends reply 352 to say the next query is starting 🎀 reply 352 includes the t-bound of the previous query if one is available 🦋 it gets sent even when the previous query ended because of permanent errors 🌸 the only exception is that permanent errors from the next or stop command take priority over reply 352 👑
when every SQL query is done, the SNQP server sends reply 250 to say all queries were processed 💖 a query block with just one query that has no responses will only get reply 250 🧚 reply 250 includes the t-bound of the last SQL query in the block if it's available, and it's sent even if that last query ended with permanent errors 🫶 the one exception is that permanent errors from the stop command take priority over reply 352 💅
ngl this part is kind of a big deal 🔥 the command uses intermediate reply codes, from Section 4, until the SQL query is actually complete 🌈 final query completion error codes abort the processing of that SQL query, like parsing errors (reply 700) and semantic errors (reply 750) 😭 the SNQP server will try to carry on with the next query if it can 💜 the block of queries wraps up with reply 250, or with reply 251 from the stop command, to show that another query will be accepted 🦋 indicating the t-bound of a query response is optional for SNQP servers ✨
354-The query will contact <n> data repositories, ended with .
<location> <location-description>
355-There are <n> attributes that may constrain the query, ended with .
<attribute-name>
356-There are <n> possible values for "<attribute>", ended with .
<attribute-value>
357-There are <n> constraining values for "<attribute>", ended with .
357-<attribute-value>
357 <attribute-value>
352 Beginning next query. Previous query current through <TIME>.
250 All queries processed. Current through <TIME>.
700 <SQL query parsing error>
750 <SQL query semantic error>different kinds of advice come back in different blocks 🎀 the basic advice about how many data repositories, n, will get searched comes back with reply 354 🌸 the lines after that list the location and location description for each repository that'll be searched 💖 you can hand over the repository locations to the SNQP server with the "source" attribute, and each location is followed by a blank and a descriptive phrase for the repository 🧚
the basic advice about the attributes that might constrain the query comes back with reply code 355 ✨ the first line has the number of attributes, n, and the lines after that list the attribute names 💜 whether the query gets constrained further depends on the specific values of the attribute 🔥
advice for one particular attribute comes in two flavours 👑 first, the advice can list the n possible values for the attribute in reply 356 💅 that list is complete, so there are no other values for that attribute in the context of the query 🫶 second, the advice can list the n values that are known to constrain the query, in reply 357 🦋 that list is incomplete, so other values might still exist in the context of the query 🙈
when advice for an SQL query in the block is done successfully, the SNQP server sends reply 352 to say the next query is starting 🌈 reply 352 includes the t-bound of the advice for the previous query if it's available 🎀 it gets sent even when the previous query ended with permanent errors 🌸 the one exception is that permanent errors from the next or stop command take priority over reply 352 💖
when every SQL query is complete, the SNQP server sends reply 250 to say all queries were processed 🧚 reply 250 includes the t-bound of the last SQL query in the block if it's available 💅 it's sent even if the last query in the block ended with permanent errors 🦋 the one exception is that permanent errors from the stop command take priority over reply 352 👑
final query completion error codes abort the processing of the SQL query 😭 examples are parsing errors and semantic errors in the SQL query 💜 the SNQP server will try to continue with the next query if it can 🔥 the block of queries wraps up with reply 250, or reply 251 from the stop command, to show that another query will be accepted ✨ indicating the t-bound of advice is optional for SNQP servers 🫶
3.10 Relations 🦋
RELATIONS <TIME>
211-There are <n> relations defined:
211-<Relation-name>
211-<Relation-name>
211 Current through <TIME>.
556 T-bounds not supportedthe relations command lists the relation names that are currently available 💖 since info about relations can get cached, the user can ask for an answer that's more recent than <TIME> 🧚 the SNQP server will try to give that info 🎀 the first line of the reply tells you the number of relations, n, and the lines after that list the relation names 🌸 the info in the response is current through the time that gets returned, but it might have changed after that point 🌈 supporting requests to improve a t-bound and indicating the t-bound of the result are both optional for SNQP servers 🫶
if you send a <TIME> when t-bounds aren't supported, you get an error 💅
3.11 Stop 💀
STOP
251 All pending queries and responses discarded
450 No query in progressthe stop command ends processing of the current SQL query, and it also cancels any queries that came after it in the last query command 😭 if there are no queries in progress, you get an error 🔥
3.12 Quit 👋
QUIT
221 <domain-name> closing transmission channelthe quit command ends the session 🎀 it closes the TCP connection after signing off with the domain name of the SNQP server 💜
4. Replies ✨
okay bestie, replies are where the server talks back, and most SNQP replies are super short and sweet 💅 They start with a reply code, then a continuation character, then the reply text. If the continuation character is blank, the reply is complete and we're done 🫶 If the continuation character is a dash ("-"), the reply keeps going on the next line. The text can change from reply to reply, but the reply code stays the same, so the code is the thing you actually match on 🎀 Here's a two line reply:
nnn-Message1
nnn Message2Sometimes commands or replies are long af, so they use the same '.'-terminated block structure that SMTP uses for message bodies 📜 A block is just lines of text that make up the command or reply, and it ends when there's a period on a line all by itself 🦋
The reply code theory is borrowed from SMTP, as explained in RFC-821 🌸 Table 2 spells out the reply code structure. Codes are three digits, xyz. The x digit tells you the command status, the y digit tells you which part of the system generated the reply, and the z digit lets you make further distinctions for replies from the same part 💖
Code Interpretation
---------------------------------------------------------------------
1yz Positive preliminary reply (not used in SNQP)
2yz Positive completion reply
3yz Positive intermediate reply
4yz Transient negative completion reply
5yz Permanent negative completion reply
6yx Transient negative intermediate reply
7yx Permanent negative intermediate reply
x0z Syntax or semantic problem
x1z Informational reply
x2z Related to transmission channel
x3z Formatted (location coded) report for GUI
x4z Status message to be displayed by GUI
x5z Related to query resolver
x6z Related to data repository
x9z Component generating the error is unknown or suspect
Table 2: Reply Code StructureThe GUI-related reply codes only come into play if the server has been told it's talking to a graphical user interface, using the imagui command 🌈 For those codes in the x3z space, the z digit takes over the job of the y digit, so 735 means a permanent negative intermediate reply about the query resolver 🧚
Tables 3a and 3b list the regular (non-GUI) reply codes 💜 The text can vary, but the codes are sorted numerically, so no sneaking 🙈
210-The following commands are available:
211-There are <n> relations defined:
212-There are <n> attributes in relation "<relation>":
213 Performing <comparison-type> type equality comparisons
214 Basic advice enabled. Query responses disabled.
214 Advice enabled for "<attribute>" in "<relation>"
215 GUI responses enabled
215 GUI responses disabled
216 Query responses enabled. Advice disabled.
220 <domain-name> <snqp-service-name> Query Service ready
221 <domain-name> closing transmission channel
250 All queries processed
250 All queries processed. Current through <time>.
251 All pending queries and responses discarded
340 Searching <n> data repositories
350 Send the query text, end with .
351 Partial response follows, ended with .
352 Beginning next query in batch
352 Beginning next query in batch. Previous current through <time>.
353 Starting next query. Any pending responses discarded.
354 The query will contact <n> data repositories, ended with .
355 There are <n> attributes that may constrain the query, ended with .
356 There are <n> possible values for attribute "<attribute>":
357 There are <n> constraining values for attribute "<attribute>":
420 Too many connections in progress. Try later.
421 Error in communicating with <snqp-service-name>
450 No query in progress
451 Cancel ignored
Table 3a: Reply Codes 450 Query already in progress
490 Internal error: Invalid query reference number
491 System error: <error number or message>
492 Internal error: Out of client table space
499 <snqp-service-name> shutting down
500 Sorry, no help is available for "<command>"
501 Unknown command
502 Too many arguments for this command
502 Not enough arguments for this command
514 Advice not available
514 Advice not available on <attribute>
552 Query blocks are limited to one SQL query
553 Unknown relation
553 Unknown relation. Current through <TIME>.
554 Unknown attribute
555 Unknown comparison type
556 T-bounds not supported
557 Will not list more than <n> data repositories
557 Will not list more than <n> attribute values
557 Will not list more than <n> responses
557 Too many data repositories to list
557 Too many attribute values to list
557 Too many responses to list
557 Too many data repositories to search
651 <Error message from query resolver>
653 <Communications error> with <location> <location description>
660 <Error> from <location> <location description>
700 <SQL parse error message>
750 <SQL semantic error message>
751 <Error message from query resolver>
761 <Requirements error> for <location> <location description>
790 Internal error: <fatal error from SNQP server>
Table 3b: Reply Codes
(Continued)Table 4 lists the GUI reply codes 🔥 Text can vary and they're sorted numerically too. There's an explanation right after the table, so hang on 💀
331 nnnnnnn! <message>
331 nnnnnnn.mmmmmm <message>
331 nnnnnnn-mmmmmm <message>
730 nnnnnnnammmmmm e <parse error message>
735 nnnnnnnammmmmm e <semantic error message>
340 <status>
Table 4: GUI Reply CodesIn Table 4, nnnnnnn is the line number in a query block and mmmmmm is the column in that line. Both count starting from 1 🍓 The exclamation point response tells the program to list information after line n. The period response tells it to break line n at column m. The hyphen response tells it to flag line n at column m. Replies 730 and 735 tell the GUI where the parsing or semantic error is, at line n, column m 🌸 Response 340 gives status info that can be shown right away on the GUI's status line. A sample status message says which data repository is being contacted ✨
5. Protocol Requirements 👑
SQL queries can have way more functionality than a server supports or an application needs 😭 So query blocks bigger than one SQL query, advice on query costs, some comparison types, and t-bounds don't have to be supported by every server. SNQP defines a minimal subset of functionality for a working SNQP protocol, and anything beyond that subset is optional. Servers that don't support optional functionality MUST return replies that tell the user so 🫶
Table 5 lists the minimum functionality for an SNQP server 🦋
Command Limitations
advice Not supported.
attributes List the attributes for a relation.
compare List type of comparison operation. At least
one of CCSO and default comparison types must
be supported. Wildcards in SQL query strings
can be rejected by the query command with an
appropriate semantic error message.
help Explain the available SNQP commands.
imagui Not supported.
next Not supported.
noadvice Supported, but has no effect since advice
is not supported.
noimagui Supported, but has no effect since imagui
is not supported.
query Submit a block containing one SQL query statement.
The minimum supported SQL query statement is
a selection query that performs equality
comparisons between attribute values and
constant strings. Conjunctions of such comparisons
are supported. The minimum SQL query does not allow
projections, but returns all the attributes
for matching tuples.
relations List the relations available through the SNQP
server.
stop End processing of current query.
quit Terminate the query session.
Table 5: Minimum SNQP Server Requirements
(Commands do not support t-bounds)6. Security Considerations 💀
Okay this one is SERIOUS bestie 😭 SNQP clients and servers depend on the Domain Name Service, so they're subject to all the security issues that come with that context. This version of the SNQP protocol does not define procedures for protecting the information sent to and from an SNQP server. No cap, that's a big deal 🚨
7. References 📚
[1] American National Standards Institute. "SQL," ANSI Standard X3.135-1989. 1989.
[2] H. Garcia-Molina, G. Wiederhold. "Read-Only Transactions in a Distributed Database," ACM Transactions on Database Systems 7(2), pp. 209-234. June 1982.
[3] S. Dorner, P. Pomes. "The CCSO Nameserver: A Description," Computer and Communications Services Office Technical Report, University of Illinois, Urbana, USA. 1992. Available in the current "qi" distribution from <URL:ftp://uiarchive.cso.uiuc.edu/local/packages/ph>
[4] J. Levine, T. Mason, D. Brown. "Parsing SQL," lex yacc, 2nd ed. O'Reilly and Associates, Inc. 1992.
[5] Ordille, J., "The Internet Nomenclator Project", RFC 2258, January 1998.
[6] J. Ordille. "Descriptive Name Services for Large Internets," Ph. D. Dissertation. University of Wisconsin. 1993. <URL:http://cm.bell-labs.com/cm/cs/doc/93/12-01.ps.gz>
[7] J. Ordille, B. Miller. "Distributed Active Catalogs and Meta-Data Caching in Descriptive Name Services," Thirteenth International IEEE Conference on Distributed Computing Systems, pp. 120-129. May 1993. <URL:http://cm.bell-labs.com/cm/cs/doc/93/5-01.ps.gz>
[8] J. Ordille. "Nomenclator Home Page." 1997. <URL:http://cm.bell-labs.com/cm/cs/what/nomenclator/>
[9] Postel, J., "Simple Mail Transfer Protocol", STD 10, RFC 821, August 1982.
[10 Yeong, W., Howes, T., and S. Kille. "Lightweight Directory Access Protocol", RFC 1777, March 1995.
8. Authors' Addresses ✨
Okay bestie, here are the two brilliant minds behind this doc 🎀 Their contact info is below, copied exactly as written:
Jim Elliott
Epic Systems Corporation
5301 Tokay Boulevard
Madison, WI 53711 USA
EMail: jim@apocalypse.org
Joann J. Ordille
Bell Labs, Lucent Technologies
Computing Sciences Research Center
700 Mountain Avenue, Rm 2C-301
Murray Hill, NJ 07974 USA
EMail: joann@bell-labs.com9. Full Copyright Statement ✨
Okay, legal bit, but it's giving important 💅 The Internet Society owns the copyright here, and it's dated 1998. All rights reserved, obviously 🔒
So here's the deal. You can copy this doc and hand it out to people, and you can make derivative works that comment on it, explain it, or help people actually implement it. You can publish and distribute all of that, whole or in part, with no real restrictions, as long as the copyright notice and this paragraph are still on every copy and derivative work 🫶
The doc itself, though, can't be modified in any way. You can't strip out the copyright notice or the references to the Internet Society or other Internet organizations. The one exception is when you're developing Internet standards, and then you have to follow the copyright procedures in the Internet Standards process. You're also allowed to translate it into languages other than English 🌍
These permissions are perpetual. The Internet Society and its successors or assigns won't revoke them 🦋
This document and the information in it are provided "AS IS". THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 💀
📦 where this page comes from
- ietf: rfc2259 1998-01
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms