34

There is chaos building in the SQL-section of the documentation.

People are adding samples from various (incompatible) SQL-dialects, and there is no mentioning which SQL-dialect it is.

For example:

  • String functions LEN and DATALENGTH, which are T-SQL exclusively.

  • in example database a sample with Id INT NOT NULL AUTO_INCREMENT, which will only ever work in MySQL, but no mentioning of that fact.

  • in like examples Match ANY versus ALL code that will only work in PostgreSQL, but no mentioning of that fact (nor any comparison of how to do it on various rdbms systems, which is what I would expect from a SQL-documentation.

Additionaly, I can't add comments to examples.
For example, there is this code in example database

CREATE TABLE Authors (
    Id INT NOT NULL AUTO_INCREMENT,
    Name VARCHAR(70) NOT NULL,
    Country VARCHAR(100) NOT NULL,
    PRIMARY KEY(Id)
);

INSERT INTO Authors
    (Name, Country)
VALUES
    ('J.D. Salinger', 'USA'),
    ('F. Scott. Fitzgerald', 'USA'),
    ('Jane Austen', 'UK'),
    ('Scott Hanselman', 'USA'),
    ('Jason N. Gaylord', 'USA'),
    ('Pranav Rastogi', 'India'),
    ('Todd Miranda', 'USA'),
    ('Christian Wenz', 'USA')
;

but I can't even add a comment to please not do this, because the countries aren't normalized (a sample should be best-practises, not some rubbish)...

17
  • 3
    heh... bluefeet was lamenting this earlier today. Got some housecleaning to do, especially when it becomes possible to move stuff between tags. Note that this was one of the earlier tags added during private beta testing, so it picked up a lot of bad habits early on.
    – Shog9
    Jul 26, 2016 at 5:02
  • 6
    The main issue is, I think, few people speaking all the SQL dialects and knowing exactly what is standard SQL and what only works in the specific vendors....
    – bwoebi
    Jul 26, 2016 at 5:09
  • 3
    @bwoebi true. Fortunately we can 'document' it ;)
    – Myrtle
    Jul 26, 2016 at 6:30
  • I think that, instead of having one tag for SQL we should have multiple tags for all (realistically most) the different types of SQL.
    – user5870134
    Jul 26, 2016 at 6:33
  • 3
    ANNNNNDDDD....welcome to the wikipedia SO-style. Unfortunately, since no one checks for the validity of the creators credentials (how can you?), then you get these trash examples. However, you might be rushing to judgement much when you say this the last example is "rubbish" just because it is not normalized to your liking. Are you sure that this is unacceptable in most situations?
    – clifton_h
    Jul 26, 2016 at 6:33
  • 1
    Use the Index, Luke and modern SQL are examples of what I consider good SQL documentation — coherent and consistently organized, with cross-platform comparisons. Jul 26, 2016 at 6:37
  • 2
    The last example doesn't break any normalisation rules (apart from non atomic name possibly) The table has a primary key, there are no repeating groups, nothing is functionally dependent on anything other than the whole key. Adding a new table for Countries with Country Code and referencing that instead would likely be beneficial but wouldn't change the normalisation. Jul 26, 2016 at 7:04
  • 1
    @Martin Smith: Not against the first 3 rules of normalization, yes. But the lesser known 3.5NF/4NF, also known as Boyce-Codd normal form (BCNF) is violated. Well arguable. But even if that sample would mean you'd use the name as a primary key in another table, it wouldn't be a good idea, irrespective of whether it violates any normal forms or not. I've seen that in my company's database, it's horrible, and it should be avoided. Someone will enter USA, the next America, the next United States, the next US, and in the end, someone is asked to make a report where you can filter the country... Jul 26, 2016 at 7:23
  • 1
    @StefanSteiger if a table doesn't have multiple overlapping candidate keys BCNF is irrelevant. It is not remotely "arguable" that it might apply here. Jul 26, 2016 at 7:27
  • 2
    Also, I just noticed Jason N. Gaylord; While funny, this definitely shouldn't be in an example database, because sooner or later, someone will show it of (for example a teacher at a [bible-belt] school), without studying the content exactly beforehand, or someone presenting a corporate information system to a customer... Silly suprises, sometimes. Jul 26, 2016 at 7:36
  • 2
    @Stefan That is a legit surname en.wikipedia.org/wiki/Gaylord. He is a published author amazon.co.uk/Jason-N.-Gaylord/e/B00BZBL07A. Jul 26, 2016 at 7:37
  • @Martin Smith: lol, OK - nice catch, but still... Jul 26, 2016 at 7:38
  • As Shog mentioned, I noticed this first thing Monday morning (blame my vacation last week for not seeing it earlier). There are definitely some issues that are popping up in the sql docs that need to be fixed. Remember that it is collaborative & examples can be edited to include headers identifying specific database platforms. I started commenting on requested topics that are not good candidates for the SQL tag because the syntax is too different in each product. I'll spend more time today, but feel free to do the same.
    – Taryn
    Jul 26, 2016 at 11:40
  • 1
    I'll add an answer a bit later on this, but I've created a chatroom for users to discuss the SQL tag/topics, etc here is a link.
    – Taryn
    Jul 26, 2016 at 20:27
  • 2
    A few of us (including @bluefeet) had a quick conversation about this just now. The upside of the current SQL chaos is that we can expect similar problems with general concept tags that have multiple and contradictory implementations. (I'm looking your way, Regular Expressions.) So this is a good test case for the process and tools we'll need to fix 'em. It might take a little longer to fix this documentation, but I hope the time will be worthwhile for future tag normalization efforts. Jul 28, 2016 at 16:11

1 Answer 1

1

According to the Documentation Update, July 25th, there will be a "Focus" section at the top. (This will not actually prevent the flood of over-specific examples, but at least might reduce it, and gives a good justification for pruning them.)

The version feature would allow marking vendor-specifc dialects. I've submitted an initial change to enable this.

Not the answer you're looking for? Browse other questions tagged .