{
    "content": [
        {
            "type": "text",
            "text": "# MongoDB::ReadPreference (perldoc)\n\n## NAME\n\nMongoDB::ReadPreference - Encapsulate and validate read preferences\n\n## SYNOPSIS\n\nuse MongoDB::ReadPreference;\n$rp = MongoDB::ReadPreference->new(); # mode: primary\n$rp = MongoDB::ReadPreference->new(\nmode     => 'primaryPreferred',\ntagsets => [ { dc => 'useast' }, {} ],\n);\n\n## DESCRIPTION\n\nA read preference indicates which servers should be used for read operations.\n\n## Sections\n\n- **NAME**\n- **VERSION**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **USAGE** (2 subsections)\n- **ATTRIBUTES**\n- **AUTHORS**\n- **COPYRIGHT AND LICENSE**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n"
        }
    ],
    "structuredContent": {
        "command": "MongoDB::ReadPreference",
        "section": "",
        "mode": "perldoc",
        "summary": "MongoDB::ReadPreference - Encapsulate and validate read preferences",
        "synopsis": "use MongoDB::ReadPreference;\n$rp = MongoDB::ReadPreference->new(); # mode: primary\n$rp = MongoDB::ReadPreference->new(\nmode     => 'primaryPreferred',\ntagsets => [ { dc => 'useast' }, {} ],\n);",
        "tldr_summary": null,
        "tldr_examples": [],
        "tldr_source": null,
        "flags": [],
        "examples": [],
        "see_also": [],
        "section_outline": [
            {
                "name": "NAME",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "VERSION",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "SYNOPSIS",
                "lines": 9,
                "subsections": []
            },
            {
                "name": "DESCRIPTION",
                "lines": 5,
                "subsections": []
            },
            {
                "name": "USAGE",
                "lines": 13,
                "subsections": [
                    {
                        "name": "Read preference modes",
                        "lines": 28
                    },
                    {
                        "name": "Tag set matching",
                        "lines": 13
                    }
                ]
            },
            {
                "name": "ATTRIBUTES",
                "lines": 28,
                "subsections": []
            },
            {
                "name": "AUTHORS",
                "lines": 10,
                "subsections": []
            },
            {
                "name": "COPYRIGHT AND LICENSE",
                "lines": 6,
                "subsections": []
            }
        ],
        "sections": {
            "NAME": {
                "content": "MongoDB::ReadPreference - Encapsulate and validate read preferences\n",
                "subsections": []
            },
            "VERSION": {
                "content": "version v2.2.2\n",
                "subsections": []
            },
            "SYNOPSIS": {
                "content": "use MongoDB::ReadPreference;\n\n$rp = MongoDB::ReadPreference->new(); # mode: primary\n\n$rp = MongoDB::ReadPreference->new(\nmode     => 'primaryPreferred',\ntagsets => [ { dc => 'useast' }, {} ],\n);\n",
                "subsections": []
            },
            "DESCRIPTION": {
                "content": "A read preference indicates which servers should be used for read operations.\n\nFor core documentation on read preference see\n<http://docs.mongodb.org/manual/core/read-preference/>.\n",
                "subsections": []
            },
            "USAGE": {
                "content": "Read preferences work via two attributes: \"mode\" and \"tagsets\". The \"mode\" parameter controls\nthe types of servers that are candidates for a read operation as well as the logic for applying\nthe \"tagsets\" attribute to further restrict the list.\n\nThe following terminology is used in describing read preferences:\n\n*   candidates – based on \"mode\", servers that could be suitable, based on \"tagsets\" and other\nlogic\n\n*   eligible – these are candidates that match \"tagsets\"\n\n*   suitable – servers that meet all criteria for a read operation\n",
                "subsections": [
                    {
                        "name": "Read preference modes",
                        "content": "primary\nOnly an available primary is suitable. \"tagsets\" do not apply and must not be provided or an\nexception is thrown.\n\nsecondary\nAll secondaries (and only secondaries) are candidates, but only eligible candidates (i.e. after\napplying \"tagsets\") are suitable.\n\nprimaryPreferred\nTry to find a server using mode \"primary\" (with no \"tagsets\"). If that fails, try to find one\nusing mode \"secondary\" and the \"tagsets\" attribute.\n\nsecondaryPreferred\nTry to find a server using mode \"secondary\" and the \"tagsets\" attribute. If that fails, try to\nfind a server using mode \"primary\" (with no \"tagsets\").\n\nnearest\nThe primary and all secondaries are candidates, but only eligible candidates (i.e. after\napplying \"tagsets\" to all candidates) are suitable.\n\nNOTE: in retrospect, the name \"nearest\" is misleading, as it implies a choice based on lowest\nabsolute latency or geographic proximity, neither which are true.\n\nThe \"nearest\" mode merely includes both primaries and secondaries without any preference between\nthe two. All are filtered on \"tagsets\". Because of filtering, servers might not be \"closest\" in\nany sense. And if multiple servers are suitable, one is randomly chosen based on the rules for\nserver selection, which again might not be the closest in absolute latency terms.\n"
                    },
                    {
                        "name": "Tag set matching",
                        "content": "The \"tagsets\" parameter is a list of tag sets (i.e. key/value pairs) to try in order. The first\ntag set in the list to match any candidate server is used as the filter for all candidate\nservers. Any subsequent tag sets are ignored.\n\nA read preference tag set (\"T\") matches a server tag set (\"S\") – or equivalently a server tag\nset (\"S\") matches a read preference tag set (\"T\") — if \"T\" is a subset of \"S\" (i.e. \"T ⊆ S\").\n\nFor example, the read preference tag set \"{ dc => 'ny', rack => 2 }\" matches a secondary server\nwith tag set \"{ dc => 'ny', rack => 2, size => 'large' }\".\n\nA tag set that is an empty document – \"{}\" – matches any server, because the empty tag set is a\nsubset of any tag set.\n"
                    }
                ]
            },
            "ATTRIBUTES": {
                "content": "mode\nThe read preference mode determines which server types are candidates for a read operation.\nValid values are:\n\n*   primary\n\n*   primaryPreferred\n\n*   secondary\n\n*   secondaryPreferred\n\n*   nearest\n\ntagsets\nThe \"tagsets\" parameter is an ordered list of tag sets used to restrict the eligibility of\nservers, such as for data center awareness.\n\nThe application of \"tagsets\" varies depending on the \"mode\" parameter. If the \"mode\" is\n'primary', then \"tagsets\" must not be supplied.\n\nmaxstalenessseconds\nThe \"maxstalenessseconds\" parameter represents the maximum replication lag in seconds (wall\nclock time) that a secondary can suffer and still be eligible for reads. The default is -1,\nwhich disables staleness checks.\n\nIf the \"mode\" is 'primary', then \"maxstalenessseconds\" must not be supplied.\n",
                "subsections": []
            },
            "AUTHORS": {
                "content": "*   David Golden <david@mongodb.com>\n\n*   Rassi <rassi@mongodb.com>\n\n*   Mike Friedman <friedo@friedo.com>\n\n*   Kristina Chodorow <k.chodorow@gmail.com>\n\n*   Florian Ragwitz <rafl@debian.org>\n",
                "subsections": []
            },
            "COPYRIGHT AND LICENSE": {
                "content": "This software is Copyright (c) 2020 by MongoDB, Inc.\n\nThis is free software, licensed under:\n\nThe Apache License, Version 2.0, January 2004\n",
                "subsections": []
            }
        }
    }
}